opensource/dify
2
0
Fork 0
mirror of https://github.com/langgenius/dify.git synced 2026-05-09 12:59:18 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(web): align tooltip migration guidance

Browse Source
This commit is contained in:
yyh 2026-05-09 12:25:33 +08:00
parent 16e0f26ea3
commit 7d27f5d6c4
No known key found for this signature in database
3 changed files with 17 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
packages/dify-ui/README.md
View File

@ -99,6 +99,13 @@ See `[web/docs/overlay-migration.md](../../web/docs/overlay-migration.md)` for t
- Never create an extra manual portal on top of our primitives — use the exported content / portal parts such as `DialogContent`, `PopoverContent`, and `DrawerPortal`. Base UI handles focus management, scroll-locking, and dismissal.
- When a primitive needs additional presentation chrome (e.g. a custom backdrop), add it **inside** the exported component, not at call sites.
### Tooltip, infotip, and popover semantics
- Use `Tooltip` only for short, non-interactive visual labels. The trigger must already have visible text or an `aria-label`; the tooltip is not the accessible name and must not contain links, buttons, forms, or structured prose.
- Use `Popover` for explanatory content, long text, rich layout, or anything users may need to reach on touch or with assistive technology. In `web/`, the `Infotip` wrapper is the preferred pattern for a `?` help glyph backed by `Popover`.
- Do not copy legacy tooltip offsets into migrated call sites. Pick a `placement` and let the primitive own spacing.
- When passing a Base UI trigger `render` prop, render a real `<button type="button">` for button-like triggers. If a Popover trigger must render a `div`, `span`, or another non-button element, pass `nativeButton={false}`.
## Development
- `pnpm -C packages/dify-ui test` — Vitest unit tests for primitives.

8
web/docs/overlay-migration.md
View File

@ -8,6 +8,7 @@ This document tracks the Dify-web migration away from legacy overlay APIs.
- Deprecated imports:
- `@/app/components/base/tooltip`
- `@/app/components/base/tooltip/content`
- `@/app/components/base/modal`
- `@/app/components/base/dialog`
- `@/app/components/base/drawer`
@ -36,6 +37,8 @@ This document tracks the Dify-web migration away from legacy overlay APIs.
1. Business/UI features outside `app/components/base/**`
- Migrate old calls to semantic primitives from `@langgenius/dify-ui/*`.
- Keep deprecated imports out of newly touched files.
- Use `@langgenius/dify-ui/tooltip` only for short, non-interactive labels where the trigger already has its own accessible name.
- Use `@langgenius/dify-ui/popover` or the web `Infotip` wrapper for explanatory, long-form, structured, or interactive content.
1. Legacy base components
- Migrate legacy base callers gradually.
- Keep deprecated imports out of newly touched files.
@ -75,6 +78,11 @@ back to `z-9999`.
parent legacy overlay should be migrated instead.
- When migrating a legacy overlay that has a high z-index, remove the z-index
entirely — the new primitive's default `z-1002` handles it.
- Do not preserve legacy tooltip offsets at call sites. Choose the nearest
`placement`/side alignment and let the primitive own its default spacing.
- When using Base UI trigger `render`, render a real `button` for button-like
triggers. If the trigger must render a non-button element, the primitive must
explicitly opt out of the native button behavior where that API is available.
### Post-migration cleanup

3
web/eslint.constants.mjs
View File

@ -49,8 +49,9 @@ export const OVERLAY_RESTRICTED_IMPORT_PATTERNS = [
group: [
'**/base/tooltip',
'**/base/tooltip/index',
'**/base/tooltip/content',
],
message: 'Deprecated: use @langgenius/dify-ui/tooltip instead. See issue #32767.',
message: 'Deprecated: use @langgenius/dify-ui/tooltip for short labels; use Popover/Infotip for rich or explanatory content. See issue #32767.',
},
{
group: [