[221_10] 改进列表的结构化插入和结构化删除 (#3296)

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: da-liii

TeXmacs/progs/generic/generic-edit.scm

@@ -366,7 +366,7 @@
 
 (tm-define (blank-list-item-stree list-type)
   (if (== list-type 'description)
-      `(item*)
+      `(item* "")
       `(item)))
 
 (tm-define (list-item-end-index item-list item-index list-type)
@@ -394,6 +394,12 @@
   (and range
        (tree-remove item-list (car range) (- (cadr range) (car range)))))
 
+(tm-define (document-empty-for-list? doc)
+  (let loop ((i 0))
+    (cond ((>= i (tree-arity doc)) #t)
+          ((list-item-node? (tree-ref doc i)) #f)
+          (else (loop (+ i 1))))))
+
 ;; 在有序和无序列表中实现缩进功能
 (tm-define (kbd-variant t forwards?)
   (:require 
@@ -1027,7 +1033,9 @@ TODO: 在文本模式中，可以自动识别剪贴板中的内容，并智能
               (if (and (tree-is? new-item 'concat)
                        (> (tree-arity new-item) 1))
                   (tree-go-to new-item 1 :end)
-                  (tree-go-to new-list insert-pos :end)))))))))
+                  (if (tree-is? new-item 'item*)
+                      (tree-go-to new-item 0 :start)
+                      (tree-go-to new-list insert-pos :end))))))))))
 
 (tm-define (structured-remove-vertical t downwards?)
   (:require (list-structured-insert-context?))
@@ -1043,9 +1051,20 @@ TODO: 在文本模式中，可以自动识别剪贴板中的内容，并智能
             (when range
               (let* ((new-list (remove-list-item-range item-list range))
                      (pos (min (car range) (- (tree-arity new-list) 1))))
-                (if (>= pos 0)
-                    (tree-go-to new-list pos :end)
-                    (tree-go-to new-list :end))))))))))
+                (if (document-empty-for-list? new-list)
+                    (let* ((list-parent (tree-up new-list))
+                           (parent-doc (and list-parent (tree-up list-parent)))
+                           (list-index (and list-parent (tree-index list-parent))))
+                      (when (and parent-doc list-index)
+                        (tree-remove parent-doc list-index 1)
+                        (if (== (tree-arity parent-doc) 0)
+                            (begin
+                              (tree-insert parent-doc 0 (list ""))
+                              (tree-go-to parent-doc 0 :end))
+                            (tree-go-to parent-doc list-index :end))))
+                    (if (>= pos 0)
+                        (tree-go-to new-list pos :end)
+                        (tree-go-to new-list :end)))))))))))
 
 (tm-define (structured-insert-extremal t forwards?)
   (structured-extremal t forwards?)

TeXmacs/tests/221_10.scm

@@ -130,7 +130,8 @@
                  (item)))))
 
 (define (test-list-structured-insert-blank-item)
-  (check (blank-list-item-stree 'enumerate) => '(item)))
+  (check (blank-list-item-stree 'enumerate) => '(item))
+  (check (blank-list-item-stree 'description) => '(item* "")))
 
 (define (test-list-structured-remove-tree-shape)
   (let* ((remove-up-doc
@@ -156,7 +157,11 @@
           (tm->tree '(document
                        (item)
                        (concat (item) "ddd")
-                       (item)))))
+                       (item))))
+         (only-list-doc
+          (tm->tree '(document
+                       (enumerate
+                         (document (concat (item) "a"))))))))
     (check (list-item-remove-range remove-up-doc 1 'enumerate #f)
            => '(0 1))
     (check (list-item-remove-range remove-down-doc 1 'enumerate #t)
@@ -174,7 +179,9 @@
     (check (remove-list-item-at bare-item-doc 0 #t)
            => '(document
                  (concat (item) "ddd")
-                 (item)))))
+                 (item)))
+    (check (remove-list-item-at only-list-doc 0 #t)
+           => '(document ""))))
 
 (tm-define (test_221_10)
   (test-list-structured-insert-end-index)

devel/221_10.md

@@ -1,5 +1,7 @@
 # [221_10] 为有序列表、无序列表和描述列表新增结构化向上/向下插入与删除
 
+> 相关文档：[201_31](201_31.md)、[x_y.md](x_y.md)（模板）
+
 ## 如何测试
 
 ### 一、单元测试
@@ -40,16 +42,57 @@
 1. 通过菜单 **Text -> Enumerate -> Default** 插入有序列表，输入至少两个条目。
 2. 重复无序列表测试中的步骤 3-9。
 3. 确认插入新条目后，编号自动重新排列。
+4. **结构化向下删除至空文档**：新建一个空白文档，仅插入一个有序列表并输入一个条目。将光标放在该条目内，按 **Alt + Delete** 删除唯一条目。确认：
+   - Mogan **不崩溃**（不会触发 "Throwing empty composite box" 错误）。
+   - 列表被自动移除，文档变为一个包含空字符串的普通段落，光标位于该段落内。
+5. **结构化向下删除后仍有内容**：新建一个文档，先输入一段普通文字，再插入一个有序列表并输入一个条目。将光标放在列表条目内，按 **Alt + Delete** 删除唯一条目。确认：
+   - 列表节点被移除，但前面的普通文字保留。
+   - 光标位于列表原来的位置（文字之后）。
 
 ### 四、描述列表（description）
 
 1. 通过菜单 **Text -> Description -> Default** 插入描述列表，输入至少两个条目，每个条目包含标签和描述内容。
-2. 将光标放在**第二个条目内部**，按 **Alt + Up**（macOS 为 **Option + Up**），确认在当前条目**上方**插入一个新的空描述条目（`item*`），且光标进入新条目的描述内容区。
-3. 将光标放在**第一个条目内部**，按 **Alt + Down**（macOS 为 **Option + Down**），确认在当前条目**下方**插入一个新的空描述条目（`item*`），且光标进入新条目的描述内容区。
+2. 将光标放在**第二个条目内部**，按 **Alt + Up**（macOS 为 **Option + Up**），确认在当前条目**上方**插入一个新的空描述条目（`item* ""`），且光标位于 `item*` 子节点 `""` 的开始位置（`tree-go-to new-item 0 :start`）。
+3. 将光标放在**第一个条目内部**，按 **Alt + Down**（macOS 为 **Option + Down**），确认在当前条目**下方**插入一个新的空描述条目（`item* ""`），且光标位于 `item*` 子节点 `""` 的开始位置（`tree-go-to new-item 0 :start`）。
 4. 将光标放在描述列表条目内部，查看焦点工具栏，确认出现 **Insert above**、**Insert below**、**Remove upwards**、**Remove downwards** 四个结构化按钮，且**不出现**左右方向的插入/删除按钮。
 5. 按 **Alt + Backspace**（macOS 为 **Option + Backspace**），确认删除当前 item 上方的同级逻辑 item（包括标签和描述内容）。
 6. 按 **Alt + Delete**（macOS 为 **Option + Delete**），确认删除当前 item 下方的同级逻辑 item（包括标签和描述内容）。
-7. 确认在描述列表中插入的新条目结构为 `item*`（而非普通列表的 `item`）。
+7. 确认在描述列表中插入的新条目结构为 `item* ""`（而非普通列表的 `item`，也非无子节点的 `item*`）。
+
+## 2026/05/08 修复描述列表插入结构与光标定位，修复空文档保护
+
+### What
+
+1. **描述列表插入结构修复**：`blank-list-item-stree` 对 `description` 类型返回 `(item* "")` 而非 `(item*)`，确保新插入的描述条目包含一个空的标签/描述内容子节点。
+2. **描述列表光标定位修复**：`structured-insert-vertical` 在插入 `item*` 后，通过 `(tree-go-to new-item 0 :end)` 将光标放入 `item*` 的子节点内部，而不是停留在 `item*` 节点上。
+3. **空文档保护修复**：`structured-remove-vertical` 在删除列表节点后，若父 `document` 的 arity 变为 0，则自动插入一个空字符串 `""` 作为占位，避免产生空的 document 触发 `TM_FAILED ("empty composite box")`。
+
+### Why
+
+1. 描述列表的 `item*` 必须包含一个子节点作为标签/描述内容，插入 `(item*)` 会导致结构不完整，后续编辑时行为异常。
+2. 光标停留在 `item*` 节点上时，用户直接输入文字不会进入标签/描述内容区，需要额外的 Enter 或点击操作才能开始编辑，体验不符合预期。
+3. 当整个文档仅包含一个有序/无序/描述列表时，结构化删除所有条目会导致列表节点被移除，根 `document` 变为空。空的 `document` 在排版阶段会创建没有任何子盒子的 composite box，触发 `composite_boxes.cpp:67` 的 `TM_FAILED ("empty composite box")`，导致 Mogan 崩溃。
+
+### How
+
+1. `blank-list-item-stree` 中 `description` 分支返回 `` `(item* "") ``。
+2. `structured-insert-vertical` 的光标定位逻辑增加对 `item*` 的判断：
+   ```scheme
+   (if (tree-is? new-item 'item*)
+       (tree-go-to new-item 0 :end)
+       (tree-go-to new-list insert-pos :end))
+   ```
+3. `structured-remove-vertical` 在删除列表节点后增加空文档保护：
+   ```scheme
+   (when (and parent-doc list-index)
+     (tree-remove parent-doc list-index 1)
+     (if (== (tree-arity parent-doc) 0)
+         (begin
+           (tree-insert parent-doc 0 (list ""))
+           (tree-go-to parent-doc 0 :end))
+         (tree-go-to parent-doc list-index :end)))
+   ```
+4. 单元测试 `221_10.scm` 新增 `blank-list-item-stree` 的 `description` 类型断言、以及 `only-list-doc` 场景的结构化删除断言。
 
 ## 2026/05/07 新增列表结构化向上/向下插入与删除