docs(media): add standalone package guide

2026-09-20 16:44:22 +08:00
parent c519d4e74b
commit eebf29c3d5
17 changed files with 326 additions and 78 deletions
@@ -1,34 +0,0 @@
---
-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.
@@ -33,7 +33,7 @@ Import the block stylesheet once from the application entry:
 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.
+Keep feature imports on their explicit subpaths. For example, importing `@workspace/blocks/notifications` does not pull chat into the same module graph. Media workflows are provided separately by `@workspace/media`.

 ## Application providers {#application-providers}

@@ -13,7 +13,7 @@ toc:

 ## 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.
+This tutorial builds an application shell step by step. You will begin with the shared layout, connect navigation, then add notifications, chat, and appearance preferences.

 By the end, the application owns its data and business rules while `@workspace/blocks` owns the reusable presentation and interaction patterns.

@@ -29,5 +29,5 @@ Blocks sit above `@workspace/ui`. They combine low-level components into feature
 2. Create the application shell.
 3. Define navigation and route state.
 4. Connect notifications.
-5. Add chat and media workflows.
+5. Add chat workflows.
 6. Finish with persistent appearance controls.
@@ -1,34 +0,0 @@
---
-title: 媒体库
-description: 提供存储 Adapter，并加入浏览、上传、文件夹和资源选择能力。
-order: 21
-toc:
-  - id: implement-the-adapter
-    title: 实现 Adapter
-  - id: provide-media
-    title: 提供媒体能力
-  - id: selection-flows
-    title: 选择流程
---
-
-## 实现 Adapter {#implement-the-adapter}
-
-`MediaAdapter` 是媒体功能完整的持久化边界。通过产品存储服务实现查询、上传、文件夹、更新和删除操作。
-
-## 提供媒体能力 {#provide-media}
-
-在媒体界面外挂载一次 Adapter：
-
-```tsx
-import { MediaLibrary, MediaProvider } from "@workspace/blocks/media"
-
-;<MediaProvider adapter={mediaAdapter} notify={showNotice}>
-  <MediaLibrary />
-</MediaProvider>
-```
-
-可选的 `notify` 回调把操作结果转换为应用的 Toast 或通知。
-
-## 选择流程 {#selection-flows}
-
-单选或多选资源使用 `MediaPickerDialog`。`readMediaDimensions`、`formatMediaFileSize` 和 `defaultMediaReference` 覆盖上传与预览相关的常用展示工作。
@@ -33,7 +33,7 @@ Blocks 使用 `@workspace/ui`、React Query 和工作区国际化运行时。工
 import "@workspace/blocks/globals.css"
 ```

-功能模块应始终从显式子路径导入。例如，导入 `@workspace/blocks/media` 不会把聊天功能加入同一个模块图。
+功能模块应始终从显式子路径导入。例如，导入 `@workspace/blocks/notifications` 不会把聊天功能加入同一个模块图。媒体工作流由独立的 `@workspace/media` 提供。

 ## 应用 Providers {#application-providers}

@@ -13,7 +13,7 @@ toc:

 ## 将要构建的内容 {#what-you-will-build}

-本教程会逐步构建一个应用外壳。你将从共享布局开始，接入导航，再添加通知、聊天、媒体和外观偏好。
+本教程会逐步构建一个应用外壳。你将从共享布局开始，接入导航，再添加通知、聊天和外观偏好。

 完成后，应用负责数据和业务规则，`@workspace/blocks` 负责可复用的展示与交互模式。

@@ -29,5 +29,5 @@ Blocks 位于 `@workspace/ui` 之上。它们将底层组件组合成完整功
 2. 创建应用外壳。
 3. 定义导航和路由状态。
 4. 接入通知。
-5. 添加聊天和媒体工作流。
+5. 添加聊天工作流。
 6. 使用持久化外观控件完成应用。