Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

docs: record overlay ownership and focus lessons (#44126)

yyh69629bd7b719
diff --git a/.agents/skills/how-to-write-component/references/interactions.md b/.agents/skills/how-to-write-component/references/interactions.md
index d90f5a05640..10e5f86990b 100644
--- a/.agents/skills/how-to-write-component/references/interactions.md
+++ b/.agents/skills/how-to-write-component/references/interactions.md
@@ -16,10 +16,12 @@ Read this document when a change involves application hotkeys, focus, dialogs, m
## Secondary Surfaces
- Follow the [overlay contract] for primitive choice and shared mechanics. The nearest consumer `AGENTS.md` owns application-specific composite reuse policy.
-- Separate behavior ownership from placement ownership: the action may own trigger, open state, and menu content while the caller owns slots, offsets, and alignment.
+- Compose Root, Trigger, and content at the entry that owns the business behavior, so the whole anatomy is visible there. A shared layer exports content and state parts; it does not take a trigger prop or wrap the Root and hide the content it renders. The caller owns slots, offsets, and alignment.
- Keep menu and dialog surfaces as siblings when a menu command opens a dialog. Mount the dialog outside popup content.
- Use the [overlay contract] to determine content lifetime and preserve the Root's closing lifecycle. Follow [state ownership] for draft placement and semantic identity; portal placement alone does not locate the state owner.
- Place query subscriptions and mutation observers at the owner whose lifetime matches when they should run. Mounted-session work may belong inside content; work that must start or stop exactly with `open` needs an explicit open-state condition.
+- Data inside a surface follows its owner's mount, not the `open` flag. A query declared in popup content under a Suspense boundary takes the content lifetime; a result the surface displays stays with its owner until that owner unmounts.
+- Anything read while a surface closes, such as the return-focus target, must come from an owner that outlives the close. The element that opened the surface may unmount with its data, and a per-call mutation callback is dropped when its component unmounts.
- Prefer primitive-owned open state unless another owner must observe or coordinate it. Analytics callbacks and local cleanup alone do not require a controlled root.
[overlay contract]: ../../../../packages/dify-ui/docs/overlays.md
diff --git a/.agents/skills/how-to-write-component/references/ownership.md b/.agents/skills/how-to-write-component/references/ownership.md
index 369e9800bc1..a72d93f0cf9 100644
--- a/.agents/skills/how-to-write-component/references/ownership.md
+++ b/.agents/skills/how-to-write-component/references/ownership.md
@@ -39,6 +39,7 @@ Read this document when adding, moving, splitting, or refactoring React componen
- Choose component declaration and export forms from the actual component contract, framework requirements, and enforced package rules. Existing style is context, not authority; do not rewrite unaffected code solely to normalize `FC`, `function`, arrow-function, named-export, or default-export forms.
- Use API-generated or API-returned types at component boundaries. Keep one-off UI refinements and conversions beside their owner.
+- Derive prop types from their source instead of writing them by hand. A prop that lands on a primitive part is typed from that part, not from a neighbouring part.
- Name props and converted data after their domain/API role, preserving traceability to the original contract.
- Preserve domain value types for selections. Do not widen enums, unions, booleans, numbers, objects, or nullable values to `string` before a real boundary requires it.
- Avoid generic `common.tsx` buckets and aliases that only rename another type. Name files, values, and public types after their domain role.
diff --git a/packages/dify-ui/docs/overlays.md b/packages/dify-ui/docs/overlays.md
index 7a6e52d72a8..72da316182a 100644
--- a/packages/dify-ui/docs/overlays.md
+++ b/packages/dify-ui/docs/overlays.md
@@ -66,6 +66,8 @@ clipped, `display: none` or unmounted, and the shared positioner class turns tha
- Use `Dialog` for modal content that needs focus containment and scroll locking.
- Use `AlertDialog` only for a destructive or must-confirm decision requiring an explicit answer.
+ It blocks outside-press dismissal but still closes on Escape; cancel that close in
+ `onOpenChange` when the answer must be explicit.
- Use `Drawer` for side-panel interactions that follow the drawer model.
- Use `DropdownMenu` for button-triggered action lists and `ContextMenu` for context actions.
A long action list filters with `DropdownMenuFilterProvider`; choosing a value is
diff --git a/packages/dify-ui/src/button/README.md b/packages/dify-ui/src/button/README.md
index f1bf7220b81..48e18c4f710 100644
--- a/packages/dify-ui/src/button/README.md
+++ b/packages/dify-ui/src/button/README.md
@@ -54,6 +54,10 @@ pending state only to `loading`; keep independent availability conditions in `di
Pass `focusableWhenDisabled={false}` only when a loading button should opt into native disabled
behavior and may leave the tab order.
+Pass `focusableWhenDisabled` on a `disabled` button only when focus must still land on it. That
+holds for the return target of a closing surface, and for a control whose tooltip explains why it
+is unavailable.
+
### Accessible loading feedback
The spinner is decorative. Keep a non-empty visible label throughout loading. If the visible label