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,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.