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,41 @@
+---
+title: Storage adapter
+description: Connect queries, uploads, mutations, URL resolution, and pagination to product infrastructure.
+order: 20
+toc:
+  - id: implement-the-contract
+    title: Implement the contract
+  - id: separate-display-and-reference-urls
+    title: Separate display and reference URLs
+  - id: preserve-query-semantics
+    title: Preserve query semantics
+---
+
+## Implement the contract {#implement-the-contract}
+
+`MediaAdapter` is the package's complete persistence boundary. Implement its asset queries, folder operations, uploads, updates, and deletes with the product's storage service.
+
+```ts
+import type { MediaAdapter } from "@workspace/media"
+
+export const mediaAdapter: MediaAdapter = {
+  listAssets: (query) => api.media.list(query),
+  listFolders: () => api.media.listFolders(),
+  upload: (input) => api.media.upload(input),
+  createFolder: (input) => api.media.createFolder(input),
+  updateFolder: (input) => api.media.updateFolder(input),
+  deleteFolder: (id) => api.media.deleteFolder(id),
+  moveAsset: (id, folderId) => api.media.move(id, folderId),
+  renameAsset: (id, name) => api.media.rename(id, name),
+  updateFavorite: (id, favorite) => api.media.favorite(id, favorite),
+  deleteAsset: (id) => api.media.delete(id),
+}
+```
+
+## Separate display and reference URLs {#separate-display-and-reference-urls}
+
+Use `resolveUrl` for short-lived signed URLs or image transformations used while rendering. Use `resolveReference` for the value returned by the picker and stored in another document. When `resolveReference` is absent, images use `defaultMediaReference`, which preserves intrinsic dimensions in the URL.
+
+## Preserve query semantics {#preserve-query-semantics}
+
+Treat `MediaAssetQuery` as an immutable request. Apply `allowedKinds`, `filter`, `folder`, and `keyword` before pagination, then return `hasNextPage` based on the filtered result. This keeps desktop and mobile filters consistent.