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
@@ -0,0 +1,31 @@
+---
+title: Overview
+description: Understand the Media package, its storage boundary, and the workflows it owns.
+order: 1
+toc:
+  - id: package-role
+    title: Package role
+  - id: capabilities
+    title: Capabilities
+  - id: design-boundary
+    title: Design boundary
+---
+
+## Package role {#package-role}
+
+`@workspace/media` provides reusable media-library and asset-picker surfaces. The host application supplies persistence through `MediaAdapter`; Media owns browsing, filtering, pagination, uploads, folders, selection, and asset actions.
+
+## Capabilities {#capabilities}
+
+- Browse images and videos with search, filters, folders, favorites, and pagination.
+- Upload to local or cloud storage targets exposed by the adapter.
+- Create, rename, nest, and delete organizational folders.
+- Select one or multiple assets through `MediaPickerDialog`.
+- Resolve display URLs and stable references independently.
+- Ship `en-US` and `zh-Hans` message catalogs.
+
+## Design boundary {#design-boundary}
+
+Media does not choose an API, database, object store, CDN, or signing strategy. The application implements those decisions behind `MediaAdapter` and can replace them without changing the interface components.
+
+> Folders classify assets inside the library. They do not need to mirror object-storage paths or change public URLs.