docs(ui): expand bilingual component guides
This commit is contained in:
Maofeng
@@ -1,30 +1,103 @@
|
||||
---
|
||||
title: Choose components
|
||||
description: Select primitives by responsibility instead of importing a single monolithic component index.
|
||||
title: Component catalog
|
||||
description: Find component entry points by responsibility and understand the local Base UI composition model.
|
||||
order: 11
|
||||
toc:
|
||||
- id: forms
|
||||
title: Forms and input
|
||||
- id: overlays
|
||||
title: Overlays and menus
|
||||
- id: content
|
||||
- id: composition-model
|
||||
title: Composition model
|
||||
- id: actions-and-forms
|
||||
title: Actions and forms
|
||||
- id: overlays-and-navigation
|
||||
title: Overlays and navigation
|
||||
- id: content-and-feedback
|
||||
title: Content and feedback
|
||||
- id: layout-and-data
|
||||
title: Layout and data
|
||||
- id: icons
|
||||
title: Icons
|
||||
---
|
||||
|
||||
## Forms and input {#forms}
|
||||
## Composition model {#composition-model}
|
||||
|
||||
Use `Button`, `Input`, `Textarea`, `Field`, and `Label` for ordinary forms. Add `Checkbox`, `RadioGroup`, `Switch`, or `Slider` for choices, and `Select`, `Combobox`, `Command`, or `Calendar` for richer selection.
|
||||
The components follow shadcn/ui's model of composing primitives from editable source, with the Base UI implementation selected in this workspace. A component is usually split into Root, Trigger, Content, Item, and related parts. The underlying primitive owns state and accessibility, while Tailwind classes and `data-slot` expose presentation.
|
||||
|
||||
## Overlays and menus {#overlays}
|
||||
Base UI uses `render` to compose a custom element, rather than the `asChild` prop commonly seen in Radix examples:
|
||||
|
||||
`Dialog`, `AlertDialog`, `Sheet`, and `Drawer` cover modal surfaces. `Popover`, `HoverCard`, and `Tooltip` provide anchored information, while the menu modules cover context, dropdown, menubar, and navigation patterns.
|
||||
```tsx
|
||||
import { Button } from "@workspace/ui/components/button"
|
||||
import { Dialog, DialogTrigger } from "@workspace/ui/components/dialog"
|
||||
|
||||
## Content and feedback {#content}
|
||||
;<Dialog>
|
||||
<DialogTrigger render={<Button variant="outline" />}>
|
||||
Edit profile
|
||||
</DialogTrigger>
|
||||
</Dialog>
|
||||
```
|
||||
|
||||
Cards, items, tables, charts, progress, skeletons, spinners, empty states, messages, and toasts provide the common display vocabulary. Accordion, Collapsible, Tabs, Carousel, and Pagination organize larger content sets.
|
||||
Use `render` only when replacing the underlying element. Pass ordinary content as children.
|
||||
|
||||
## Actions and forms {#actions-and-forms}
|
||||
|
||||
| Goal | Component entry points |
|
||||
| --------------------------- | -------------------------------------------------- |
|
||||
| Buttons and grouped actions | `button`, `button-group`, `toggle`, `toggle-group` |
|
||||
| Text input | `input`, `textarea`, `input-group`, `input-otp` |
|
||||
| Field structure | `field`, `label` |
|
||||
| Boolean and single choice | `checkbox`, `switch`, `radio-group` |
|
||||
| Range and progress | `slider`, `progress` |
|
||||
| Options and commands | `native-select`, `select`, `combobox`, `command` |
|
||||
| Dates | `calendar` |
|
||||
|
||||
Prefer `NativeSelect` for simple, mobile-friendly choices that do not need a custom popup. Choose `Combobox`, `Select`, or `Command` when the interaction needs search, custom items, or command behavior.
|
||||
|
||||
## Overlays and navigation {#overlays-and-navigation}
|
||||
|
||||
| Goal | Component entry points |
|
||||
| ------------------------------ | -------------------------------------------------------- |
|
||||
| Modal confirmation and editing | `alert-dialog`, `dialog`, `sheet`, `drawer` |
|
||||
| Anchored content | `popover`, `hover-card`, `tooltip`, `anchored-surface` |
|
||||
| Menus | `dropdown-menu`, `context-menu`, `menubar` |
|
||||
| Page navigation | `breadcrumb`, `navigation-menu`, `pagination`, `sidebar` |
|
||||
|
||||
Dialog, Sheet, and Drawer expose controlled state and composable parts. Use `AlertDialog` for consequential destructive actions, `Tooltip` for brief descriptions, and `Popover` for an anchored panel containing interactive controls.
|
||||
|
||||
## Content and feedback {#content-and-feedback}
|
||||
|
||||
| Goal | Component entry points |
|
||||
| ------------------------- | ----------------------------------------------------- |
|
||||
| Containers and states | `card`, `item`, `empty`, `alert`, `badge`, `marker` |
|
||||
| Loading and notifications | `skeleton`, `spinner`, `toast` |
|
||||
| Messaging UI | `message`, `bubble`, `attachment`, `message-scroller` |
|
||||
| Sectioned content | `accordion`, `collapsible`, `tabs`, `carousel` |
|
||||
|
||||
`Message` owns participant layout, alignment, and metadata; `Bubble` owns the message surface; `Attachment` expresses an upload lifecycle; and `MessageScroller` handles follow mode and jump controls. They are presentation primitives and do not own conversation data.
|
||||
|
||||
## Layout and data {#layout-and-data}
|
||||
|
||||
| Goal | Component entry points |
|
||||
| -------------- | ------------------------------------------------------- |
|
||||
| Data display | `table`, `chart` |
|
||||
| Layout | `separator`, `aspect-ratio`, `resizable`, `scroll-area` |
|
||||
| Direction | `direction` |
|
||||
| Keyboard hints | `kbd` |
|
||||
| Avatars | `avatar` |
|
||||
|
||||
The chart module wraps Recharts containers, tooltips, legends, and style mappings without choosing an application data model. `DirectionProvider` re-exports Base UI's direction context; the page should still synchronize the HTML `dir` attribute.
|
||||
|
||||
## Icons {#icons}
|
||||
|
||||
Import named icons from `@workspace/ui/components/icon`. The module centralizes the `@icones/react` vocabulary so applications and packages use the same icon source.
|
||||
Import named icons from the local Icones adapter:
|
||||
|
||||
```tsx
|
||||
import { SearchIcon, SettingsIcon } from "@workspace/ui/components/icon"
|
||||
```
|
||||
|
||||
Components provide a default size to SVGs that do not have an explicit size class. Icon buttons still require an accessible name:
|
||||
|
||||
```tsx
|
||||
<Button size="icon" aria-label="Search">
|
||||
<SearchIcon aria-hidden="true" />
|
||||
</Button>
|
||||
```
|
||||
|
||||
Do not reintroduce `lucide-react` in new components. Register additional icons through `createIcon` in `components/icon.tsx` so the workspace keeps one icon path.
|
||||
|
||||
Reference in New Issue
Block a user