feat(docs): add bilingual package documentation site
This commit is contained in:
Maofeng
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Appearance
|
||||
description: Finish the application with persistent theme, color, and compact-layout preferences.
|
||||
order: 22
|
||||
toc:
|
||||
- id: provide-ui-state
|
||||
title: Provide UI state
|
||||
- id: apply-preferences
|
||||
title: Apply preferences
|
||||
- id: add-locales
|
||||
title: Add locales
|
||||
---
|
||||
|
||||
## Provide UI state {#provide-ui-state}
|
||||
|
||||
Mount `UiStateProvider` near the application root. A controlled provider can persist every state update through its change handler.
|
||||
|
||||
```tsx
|
||||
<UiStateProvider>
|
||||
<AppearanceController />
|
||||
<App />
|
||||
<ThemeToggleButton />
|
||||
</UiStateProvider>
|
||||
```
|
||||
|
||||
## Apply preferences {#apply-preferences}
|
||||
|
||||
Render `AppearanceController` once so the current state becomes document classes and theme variables. `useUiState` reads or updates individual preferences, while `useResolvedTheme` returns the effective light or dark scheme after resolving system mode.
|
||||
|
||||
## Add locales {#add-locales}
|
||||
|
||||
Add the appearance catalog only when the application uses these controls:
|
||||
|
||||
```json
|
||||
{
|
||||
"catalogSources": ["@workspace/blocks/appearance/locales/{locale}"]
|
||||
}
|
||||
```
|
||||
|
||||
The application shell is now complete. Add only the other block-specific catalogs used by the product.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Media library
|
||||
description: Supply a storage adapter and add browsing, upload, folders, and asset selection.
|
||||
order: 21
|
||||
toc:
|
||||
- id: implement-the-adapter
|
||||
title: Implement the adapter
|
||||
- id: provide-media
|
||||
title: Provide media
|
||||
- id: selection-flows
|
||||
title: Selection flows
|
||||
---
|
||||
|
||||
## Implement the adapter {#implement-the-adapter}
|
||||
|
||||
`MediaAdapter` is the media feature's complete persistence boundary. Implement its query, upload, folder, update, and delete operations with the product's storage service.
|
||||
|
||||
## Provide media {#provide-media}
|
||||
|
||||
Mount the adapter once around the media surfaces:
|
||||
|
||||
```tsx
|
||||
import { MediaLibrary, MediaProvider } from "@workspace/blocks/media"
|
||||
|
||||
;<MediaProvider adapter={mediaAdapter} notify={showNotice}>
|
||||
<MediaLibrary />
|
||||
</MediaProvider>
|
||||
```
|
||||
|
||||
The optional `notify` callback translates operational results into the application's toast or notification system.
|
||||
|
||||
## Selection flows {#selection-flows}
|
||||
|
||||
Use `MediaPickerDialog` for single or multiple asset selection. `readMediaDimensions`, `formatMediaFileSize`, and `defaultMediaReference` cover the common presentation work around uploads and previews.
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: Notifications
|
||||
description: Connect notification state without coupling the UI to a backend.
|
||||
order: 20
|
||||
toc:
|
||||
- id: notifications-query
|
||||
title: Notifications query
|
||||
---
|
||||
|
||||
## Notifications query {#notifications-query}
|
||||
|
||||
Notifications use TanStack Query as their data boundary:
|
||||
|
||||
```tsx
|
||||
const notifications = useNotifications({
|
||||
queryKey: ["notifications"],
|
||||
queryFn: loadNotifications,
|
||||
})
|
||||
```
|
||||
|
||||
The result includes unread counts, optimistic read-state updates, action execution, refetching, and pending or error status. `AppLayout` can create the sheet directly from the same query options.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Chats
|
||||
description: Add a responsive conversation workspace and connect its events to application services.
|
||||
order: 30
|
||||
toc:
|
||||
- id: render-the-workspace
|
||||
title: Render the workspace
|
||||
- id: controlled-state
|
||||
title: Controlled state
|
||||
- id: media-and-pagination
|
||||
title: Media and pagination
|
||||
---
|
||||
|
||||
## Render the workspace {#render-the-workspace}
|
||||
|
||||
`ChatWorkspace` renders conversation discovery, the active thread, and the composer:
|
||||
|
||||
```tsx
|
||||
import { ChatWorkspace } from "@workspace/blocks/chats"
|
||||
|
||||
;<ChatWorkspace
|
||||
conversations={conversations}
|
||||
onSend={({ conversation, message }) => sendMessage(conversation, message)}
|
||||
/>
|
||||
```
|
||||
|
||||
## Controlled state {#controlled-state}
|
||||
|
||||
The active conversation, draft, search query, and Enter-to-send preference can be controlled individually. Leave a value undefined when the workspace should own that state.
|
||||
|
||||
The UI emits events but does not select a transport or persistence format. Map API responses into `ChatConversation` and the exported message variants at the application boundary.
|
||||
|
||||
## Media and pagination {#media-and-pagination}
|
||||
|
||||
Provide `resolveMediaUrl` when stored media references need signed or transformed URLs. Use `onLoadEarlierMessages` with `hasMoreMessages` and `isLoadingMoreMessages` to connect historical pagination.
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: Application shell
|
||||
description: Assemble the shared header, sidebar, breadcrumbs, chat, and notification surfaces.
|
||||
order: 11
|
||||
toc:
|
||||
- id: render-app-layout
|
||||
title: Render AppLayout
|
||||
- id: layout-inputs
|
||||
title: Layout inputs
|
||||
- id: optional-preset
|
||||
title: Optional preset
|
||||
---
|
||||
|
||||
## Render AppLayout {#render-app-layout}
|
||||
|
||||
`AppLayout` is the integration point for the rest of this tutorial:
|
||||
|
||||
```tsx
|
||||
import { AppLayout } from "@workspace/blocks/layout"
|
||||
|
||||
export function WorkspaceLayout() {
|
||||
return (
|
||||
<AppLayout
|
||||
navigationGroups={navigationGroups}
|
||||
notifications={{
|
||||
queryKey: ["notifications"],
|
||||
queryFn: loadNotifications,
|
||||
}}
|
||||
chatThreads={chatThreads}
|
||||
>
|
||||
<Outlet />
|
||||
</AppLayout>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Layout inputs {#layout-inputs}
|
||||
|
||||
The shell composes `AppSidebar`, `AppBreadcrumb`, `AppQueryIndicator`, `UserMenu`, a notification sheet, and chat threads. Pass `headerActions` when the product needs additional global controls.
|
||||
|
||||
The route content remains the layout's `children`, so the package does not constrain the router used by the application.
|
||||
|
||||
## Optional preset {#optional-preset}
|
||||
|
||||
`@workspace/blocks/layouts/vega` provides an optional visual shell. It lives on a separate entry point so the standard layout does not include preset-specific code.
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Installation
|
||||
description: Add the package, its styles, and the providers required by the tutorial.
|
||||
order: 10
|
||||
toc:
|
||||
- id: add-the-package
|
||||
title: Add the package
|
||||
- id: import-styles
|
||||
title: Import styles
|
||||
- id: application-providers
|
||||
title: Application providers
|
||||
---
|
||||
|
||||
## Add the package {#add-the-package}
|
||||
|
||||
Add the workspace dependency to the consuming application:
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"@workspace/blocks": "workspace:*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Blocks use `@workspace/ui`, React Query, and the workspace internationalization runtime. The workspace package manager resolves those dependencies for local applications.
|
||||
|
||||
## Import styles {#import-styles}
|
||||
|
||||
Import the block stylesheet once from the application entry:
|
||||
|
||||
```ts
|
||||
import "@workspace/blocks/globals.css"
|
||||
```
|
||||
|
||||
Keep feature imports on their explicit subpaths. For example, importing `@workspace/blocks/media` does not pull chat into the same module graph.
|
||||
|
||||
## Application providers {#application-providers}
|
||||
|
||||
The full shell expects React Query and internationalization to be available above it. Add those providers before the route tree, then continue to the application-shell chapter.
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Navigation
|
||||
description: Define navigation groups once and connect them to desktop and mobile surfaces.
|
||||
order: 12
|
||||
toc:
|
||||
- id: define-groups
|
||||
title: Define groups
|
||||
- id: provide-navigation
|
||||
title: Provide navigation
|
||||
- id: route-state
|
||||
title: Route state
|
||||
---
|
||||
|
||||
## Define groups {#define-groups}
|
||||
|
||||
Start with typed `NavigationGroup` values. Items may represent direct routes or nested navigation branches.
|
||||
|
||||
```ts
|
||||
import type { NavigationGroup } from "@workspace/blocks/navigation"
|
||||
|
||||
export const navigationGroups: NavigationGroup[] = [
|
||||
{
|
||||
id: "workspace",
|
||||
label: "Workspace",
|
||||
items: [
|
||||
{ id: "dashboard", label: "Dashboard", to: "/dashboard" },
|
||||
{ id: "media", label: "Media", to: "/media" },
|
||||
],
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
## Provide navigation {#provide-navigation}
|
||||
|
||||
`AppLayout` already mounts the provider and the responsive navigation surfaces. For a custom shell, compose them directly:
|
||||
|
||||
```tsx
|
||||
<NavigationProvider groups={navigationGroups}>
|
||||
<PrimaryNavigation groups={navigationGroups} />
|
||||
<MobileNavigationSheet groups={navigationGroups} />
|
||||
</NavigationProvider>
|
||||
```
|
||||
|
||||
## Route state {#route-state}
|
||||
|
||||
Use `resolveNavigationRouteState` for the standard route model. Applications with custom routing can supply a `GetNavigationRouteState` implementation while keeping the same navigation UI.
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: Overview
|
||||
description: Understand how the Blocks package turns UI primitives into complete application features.
|
||||
order: 1
|
||||
toc:
|
||||
- id: what-you-will-build
|
||||
title: What you will build
|
||||
- id: design-boundary
|
||||
title: Design boundary
|
||||
- id: tutorial-map
|
||||
title: Tutorial map
|
||||
---
|
||||
|
||||
## What you will build {#what-you-will-build}
|
||||
|
||||
This tutorial builds an application shell step by step. You will begin with the shared layout, connect navigation, then add notifications, chat, media, and appearance preferences.
|
||||
|
||||
By the end, the application owns its data and business rules while `@workspace/blocks` owns the reusable presentation and interaction patterns.
|
||||
|
||||
## Design boundary {#design-boundary}
|
||||
|
||||
Blocks sit above `@workspace/ui`. They combine low-level components into features, but they do not choose your API, database, router configuration, or storage provider.
|
||||
|
||||
> Keep data access in the host application. Pass it into a block through props, query functions, providers, or adapters.
|
||||
|
||||
## Tutorial map {#tutorial-map}
|
||||
|
||||
1. Install the package and global styles.
|
||||
2. Create the application shell.
|
||||
3. Define navigation and route state.
|
||||
4. Connect notifications.
|
||||
5. Add chat and media workflows.
|
||||
6. Finish with persistent appearance controls.
|
||||
Reference in New Issue
Block a user