feat(site): add component documentation site

Add Vite, React, MDX, and Tailwind documentation infrastructure. Document component, handbook, overview, and utility routes. Add interactive examples for every component family. Deduplicate React resolution and load the Tailwind 4 theme configuration.
2026-07-25 06:03:17 +08:00
parent b3a7a2a8f5
commit 4efe3f3c64
185 changed files with 18809 additions and 0 deletions
@@ -0,0 +1,77 @@
+# Button
+
+Button wraps Base UI's button primitive with the Tailwind classes from the official Base UI example.
+
+::example{src="components/button/button.tsx"}
+
+## Anatomy
+
+### Base UI Style
+
+```tsx
+import Button from "@/components/ui/button"
+
+<Button focusableWhenDisabled>Save changes</Button>
+```
+
+### Shadcn Style
+
+```tsx
+import { Button } from "@/components/ui/button"
+
+<Button>Save changes</Button>
+```
+
+## Composition
+
+Use the following composition to build `Button`:
+
+```txt
+Button
+```
+
+## Examples
+
+These examples mirror the usage patterns documented by Base UI for Button.
+
+### Rendering as another tag
+
+The button can remain keyboard accessible while being rendered as another tag, such as a `<div>`, by specifying `nativeButton={false}`.
+
+```jsx
+import Button from "@/components/ui/button"
+
+<Button render={<div />} nativeButton={false}>
+  Button that can contain complex children
+</Button>;
+```
+
+### Rendering links as buttons
+
+The Button component enforces button semantics. `nativeButton={false}` signals that the rendered tag is not a `<button>`, but it must still be a tag that can receive button semantics (`role="button"`, keyboard interaction handlers). Links (`<a>`) have their own semantics and should not be rendered as buttons through the `render` prop.
+
+### Loading states
+
+For buttons that enter a loading state after being clicked, specify the `focusableWhenDisabled` prop to ensure focus remains on the button when it becomes disabled. This prevents focus from being lost and maintains the tab order.
+
+
+### Loading states
+
+::example{src="components/button/loading-states.tsx"}
+
+## API Reference
+
+Official API: [Base UI Button API](https://base-ui.com/react/components/button#api-reference).
+
+This wrapper preserves the underlying Base UI Button API. Styled parts forward `className`, `style`, and `render` where Base UI supports them.
+
+### Root
+
+`Button` exposes the corresponding Base UI part with the wrapper's Tailwind styles.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `defaultValue` / `defaultOpen` | `any` | - | Initial uncontrolled value or open state when supported. |
+| `value` / `open` | `any` | - | Controlled value or open state when supported. |
+| `onValueChange` / `onOpenChange` | `function` | - | Called when controlled state changes. |
+| `children` | `React.ReactNode` | - | Child parts rendered inside the root. |