fix(focus-trap): align containment contract with implementation (#307)

* fix(focus-trap): align containment contract with implementation

* test(focus-trap): address review feedback

Author: RtlZeroMemory

docs/widgets/catalog.json

@@ -241,9 +241,9 @@
     },
     {
       "name": "focusTrap",
-      "requiredProps": ["id"],
-      "commonProps": ["children"],
-      "example": "ui.focusTrap({ id: 'trap' }, [ui.input('q', '')])"
+      "requiredProps": ["id", "active"],
+      "commonProps": ["initialFocus", "returnFocusTo", "children"],
+      "example": "ui.focusTrap({ id: 'trap', active: true }, [ui.input({ id: 'q', value: '' })])"
     },
     {
       "name": "virtualList",

docs/widgets/focus-trap.md

@@ -8,17 +8,34 @@ Constrains focus within a subtree when active. Used by modals and overlays to pr
 ui.focusTrap(
   { id: "modal-trap", active: state.modalOpen },
   [
-    ui.text("Are you sure?"),
-    ui.button({ id: "confirm", label: "Confirm" }),
-    ui.button({ id: "cancel", label: "Cancel" }),
+    ui.column({ gap: 1 }, [
+      ui.text("Are you sure?"),
+      ui.row({ gap: 1 }, [
+        ui.button({ id: "confirm", label: "Confirm" }),
+        ui.button({ id: "cancel", label: "Cancel" }),
+      ]),
+    ]),
   ]
 )
 ```
 
 ## Layout behavior
 
-`focusTrap` is layout-transparent and does not impose a hidden column layout.
-Children keep their native layout semantics (`row`, `column`, `grid`, etc.).
+`focusTrap` is layout-transparent when it wraps a single child.
+That child keeps its native layout semantics (`row`, `column`, `grid`, etc.).
+
+For legacy multi-child usage, direct children fall back to an implicit column layout.
+Prefer an explicit container inside the trap when you need more than one child:
+
+```typescript
+ui.focusTrap(
+  { id: "trap-legacy", active: true },
+  [
+    ui.button({ id: "a", label: "A" }),
+    ui.button({ id: "b", label: "B" }),
+  ]
+)
+```
 
 When you want explicit arrangement, compose a normal layout container inside the trap:
 
@@ -48,12 +65,14 @@ ui.focusTrap(
 
 When `active` is `true`:
 
-- Tab/Shift+Tab cycles only through focusable elements inside the trap
-- Focus cannot escape to elements outside the trap
+- If the trap contains focusable elements, Tab/Shift+Tab cycles only through those elements
+- Containment is focus-system based; `focusTrap` alone does not define an outside click boundary
 - Attempting to Tab past the last element wraps to the first
 - Attempting to Shift+Tab before the first element wraps to the last
 - The trap is collected into the focus system (`CollectedTrap`) so modal overlays
   consistently block/contain background focus.
+- If the active trap has no focusable descendants, it preserves the current focus unless
+  `initialFocus` names a valid nested target.
 
 When `active` becomes `false`:
 
@@ -128,7 +147,8 @@ ui.focusTrap({ id: "outer", active: true }, [
 
 ## Mouse Behavior
 
-When a focus trap is active, mouse clicks outside the trap region are blocked. Clicking widgets inside the trap works normally — the clicked widget receives focus.
+`focusTrap` does not block outside clicks by itself.
+Use it with `ui.modal()` or a layer-backed overlay when you need pointer containment as well as Tab containment.
 
 ## Related
 

packages/core/src/layout/__tests__/layout.focusZone.test.ts

@@ -97,4 +97,20 @@ describe("focusZone/focusTrap layout transparency", () => {
     assert.equal(first.rect.y, second.rect.y);
     assert.equal(second.rect.x > first.rect.x, true);
   });
+
+  test("focusTrap with multiple direct children keeps legacy column fallback", () => {
+    const vnode = ui.focusTrap({ id: "trap-legacy", active: true }, [
+      ui.button({ id: "trap-legacy-a", label: "A" }),
+      ui.button({ id: "trap-legacy-b", label: "B" }),
+    ]);
+
+    const laidOut = mustLayout(vnode, 20, 8);
+    const first = laidOut.children[0];
+    const second = laidOut.children[1];
+    assert.ok(first && second, "legacy fallback should lay out both direct children");
+    if (!first || !second) return;
+
+    assert.equal(second.rect.y > first.rect.y, true);
+    assert.equal(second.rect.x, first.rect.x);
+  });
 });