feat(docs): add bilingual package documentation site

2026-09-20 15:53:28 +08:00
parent 60f6f1fb1a
commit dc80bd8ae0
111 changed files with 6531 additions and 0 deletions
@@ -0,0 +1,31 @@
+---
+title: Add responsive behavior
+description: Use shared breakpoint and interaction hooks when CSS alone cannot express the behavior.
+order: 20
+toc:
+  - id: breakpoints
+    title: Breakpoints
+  - id: server-rendering
+    title: Server rendering
+  - id: ripple
+    title: Ripple interaction
+---
+
+## Breakpoints {#breakpoints}
+
+```tsx
+import { useBreakpoint, useIsMobile } from "@workspace/ui/hooks/use-breakpoint"
+
+const breakpoint = useBreakpoint()
+const isMobile = useIsMobile()
+```
+
+Prefer CSS responsive variants for visual changes. Use these hooks only when component behavior or mounted content must change.
+
+## Server rendering {#server-rendering}
+
+The breakpoint store uses a deterministic desktop server snapshot. `getBreakpointInitializationScript` can assign the matching root class before hydration when the application needs CSS and behavioral breakpoints to agree immediately.
+
+## Ripple interaction {#ripple}
+
+`useRipple` returns a ref callback that adds pointer-driven feedback to an interactive element. The element should establish a positioned containing block so the generated overlay uses the correct bounds.
@@ -0,0 +1,36 @@
+---
+title: Localize UI
+description: Load only the UI catalog and calendar locale required by the active language.
+order: 21
+toc:
+  - id: catalog-source
+    title: Catalog source
+  - id: direct-imports
+    title: Direct imports
+  - id: supported-locales
+    title: Supported locales
+---
+
+## Catalog source {#catalog-source}
+
+Add the UI locale source to the application's internationalization configuration:
+
+```json
+{
+  "catalogSources": ["@workspace/ui/locales/{locale}"]
+}
+```
+
+The locales root contains metadata and types. It does not import every language catalog.
+
+## Direct imports {#direct-imports}
+
+```ts
+import { calendarLocale, messages } from "@workspace/ui/locales/en-US"
+```
+
+Each language entry also exports its matching `react-day-picker` locale.
+
+## Supported locales {#supported-locales}
+
+The UI catalogs include American English (`en-US`) and Simplified Chinese (`zh-Hans`).
@@ -0,0 +1,37 @@
+---
+title: Compose a form
+description: Combine field, input, and button primitives while keeping domain state in the application.
+order: 30
+toc:
+  - id: create-the-form
+    title: Create the form
+  - id: validation
+    title: Validation
+  - id: styling
+    title: Styling
+---
+
+## Create the form {#create-the-form}
+
+```tsx
+import { Button } from "@workspace/ui/components/button"
+import { Field, FieldError, FieldLabel } from "@workspace/ui/components/field"
+import { Input } from "@workspace/ui/components/input"
+
+;<form onSubmit={saveProfile}>
+  <Field>
+    <FieldLabel htmlFor="display-name">Display name</FieldLabel>
+    <Input id="display-name" name="displayName" />
+    <FieldError>{errors.displayName}</FieldError>
+  </Field>
+  <Button type="submit">Save profile</Button>
+</form>
+```
+
+## Validation {#validation}
+
+The UI package renders validation state but does not select a form library or schema. Connect native form data, React state, or a form framework at the application boundary.
+
+## Styling {#styling}
+
+Use component variants for supported semantic changes and `className` for local layout. Use `cn` from `@workspace/ui/lib/utils` when conditional classes or consumer overrides must be merged.
@@ -0,0 +1,30 @@
+---
+title: Choose components
+description: Select primitives by responsibility instead of importing a single monolithic component index.
+order: 11
+toc:
+  - id: forms
+    title: Forms and input
+  - id: overlays
+    title: Overlays and menus
+  - id: content
+    title: Content and feedback
+  - id: icons
+    title: Icons
+---
+
+## Forms and input {#forms}
+
+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.
+
+## Overlays and menus {#overlays}
+
+`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.
+
+## Content and feedback {#content}
+
+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.
+
+## 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.
@@ -0,0 +1,39 @@
+---
+title: Project setup
+description: Import the global stylesheet and begin with explicit component subpaths.
+order: 10
+toc:
+  - id: import-styles
+    title: Import styles
+  - id: import-a-component
+    title: Import a component
+  - id: entry-points
+    title: Entry points
+---
+
+## Import styles {#import-styles}
+
+Import the global stylesheet once at the application entry:
+
+```ts
+import "@workspace/ui/globals.css"
+```
+
+It provides the shared Tailwind layers, design variables, font setup, and utilities expected by the components.
+
+## Import a component {#import-a-component}
+
+```tsx
+import { Button } from "@workspace/ui/components/button"
+
+export function SaveButton() {
+  return <Button>Save</Button>
+}
+```
+
+## Entry points {#entry-points}
+
+- `@workspace/ui/components/*` exposes one component module.
+- `@workspace/ui/hooks/*` exposes reusable interactions and media-query state.
+- `@workspace/ui/lib/utils` exposes shared class-name composition.
+- `@workspace/ui/locales/*` exposes language-specific catalogs.
@@ -0,0 +1,24 @@
+---
+title: Overview
+description: Learn where the UI package fits and how its explicit entry points support composition.
+order: 1
+toc:
+  - id: package-role
+    title: Package role
+  - id: tutorial-map
+    title: Tutorial map
+  - id: ui-or-blocks
+    title: UI or Blocks
+---
+
+## Package role {#package-role}
+
+`@workspace/ui` contains reusable React primitives, composite controls, hooks, icons, styles, and locale catalogs. It is the visual foundation shared by applications and higher-level feature packages.
+
+## Tutorial map {#tutorial-map}
+
+This tutorial installs the styles, introduces component subpaths, builds a small form through composition, adds responsive behavior, and connects locale catalogs.
+
+## UI or Blocks {#ui-or-blocks}
+
+Use UI components when the application owns the workflow. Use `@workspace/blocks` when the interface also needs a complete feature contract such as navigation, media storage, search adapters, or notification queries.