sanity-plugin-media 2.0.0-alpha.1 → 2.0.0-v3-studio.0

package/README.md

@@ -1,14 +1,23 @@
 # Sanity Media
 
+> ⚠️ This version of `sanity-plugin-media` is for [Sanity Studio V3](https://www.sanity.io/blog/sanity-studio-v3-developer-preview), which is currently in developer preview.
+>
+> The Studio V2 compatible version can be found on the [V2 branch](https://github.com/robinpyon/sanity-plugin-media).
+
+## What is it?
+
 ![npm-v](https://img.shields.io/npm/v/sanity-plugin-media?style=flat-square)
 ![npm-dw](https://img.shields.io/npm/dw/sanity-plugin-media?style=flat-square)
 
 A convenient way to browse, manage and refine your [Sanity](https://www.sanity.io/) assets.
 
-Use it standalone as a browser, or optionally hook it up as a [custom asset source](https://www.sanity.io/docs/custom-asset-sources) and use it to power asset selection too.
+Use it standalone as a browser, or optionally hook it up as a [custom asset source](https://www.sanity.io/docs/custom-asset-sources) and use it to power both image and file selection too.
 
 ![Grid view](https://user-images.githubusercontent.com/209129/108927411-21aa7f00-7638-11eb-9cf7-334598ac4103.png)
-![Asset view](https://user-images.githubusercontent.com/209129/105532355-9fe6cf00-5ce2-11eb-9982-b2bfd22f3409.png)
+_Default grid view_
+
+![Asset view](https://user-images.githubusercontent.com/209129/132573482-fa866da9-7ee0-42db-b39f-25a0e48bba9f.png)
+_Individual asset view_
 
 ## Features
 
@@ -29,51 +38,75 @@ Use it standalone as a browser, or optionally hook it up as a [custom asset sour
 
 #### Built for large datasets and collaborative editing in mind
 
-- Virtualized grid + tabular views for super speedy browsing, even with thousands of assets
+- Virtualized grid + tabular views for super speedy browsing, even with thousands of assets and tags
 - Utilises Sanity's [real time updates](https://www.sanity.io/docs/realtime-updates) for live changes from other studio members
 
-#### Fits right in with your Sanity studio!
+#### Fits right in with your Sanity studio
 
 - Built with the same [UI components Sanity uses](https://www.sanity.io/ui) under the hood
 - Fully responsive and mobile friendly
 
-## Install
+## Install (V3 Studio only)
 
-In your Sanity project folder:
+In your Sanity project folder, install the plugin and its peer dependency:
 
 ```sh
-sanity install media
+npm install --save sanity-plugin-media@v3-studio @mdx-js/react
 ```
 
-This will add the Media button to your studio menu. If this is all you're after – that's all you need to do!
+or
 
-### Enabling it as a global [custom asset source](https://www.sanity.io/docs/custom-asset-sources)
+```sh
+yarn add sanity-plugin-media@v3-studio @mdx-js/react
+```
 
-You'll need to do this if you want to use the plugin when selecting images.
+`@mdx-js/react` will be removed as a dependency in a future version.
 
-This plugin exposes `part:sanity-plugin-media/asset-source` which you import when defining custom asset sources.
+## Usage
 
-In `sanity.json`, add the following snippet to the `parts` array:
+Add it as a plugin in your `sanity.config.ts` (or .js) file:
 
-```json
-{
-  "implements": "part:@sanity/form-builder/input/image/asset-sources",
-  "path": "./parts/assetSources.js"
-}
+```js
+import {media} from 'sanity-plugin-media'
+
+export default createConfig({
+  // ...
+  plugins: [media()]
+})
 ```
 
-In `./parts/assetSources.js`:
+This will enable the Media plugin as both a standalone tool (accessible in your studio menu) and as an additional asset source for your image and file fields.
 
-```js
-import MediaAssetSource from 'part:sanity-plugin-media/asset-source'
+### Customizing the asset source
 
-export default [MediaAssetSource]
-```
+You can configure your studio to use this asset source either exclusively, or conditionally enable it based on the type of asset (image or file).
 
-That's it! The browser will now pop up every time you try select an image.
+```js
+import {media, mediaAssetSource} from 'sanity-plugin-media'
+
+export default createConfig({
+  // ...
+  plugins: [media()],
+  form: {
+    // Don't use this plugin when selecting files only (but allow all other enabled asset sources)
+    file: {
+      assetSources: previousAssetSources => {
+        return previousAssetSources.filter(assetSource => assetSource !== mediaAssetSource)
+      }
+    }
+  }
+})
+```
 
 ## Known issues
 
+<details>
+<summary>(V3) Where has the references tab gone?</summary>
+
+- This will be enabled in a future version!
+
+</details>
+
 <details>
 <summary>There isn't a way to edit asset fields directly from the desk (without opening the plugin)</summary>
 
@@ -101,13 +134,6 @@ That's it! The browser will now pop up every time you try select an image.
 
 </details>
 
-<details>
-<summary>There isn't a way to use the plugin to select file (non-image) assets</summary>
-
-- This will be possible if and when Sanity enables custom asset sources on `file` fields.
-
-</details>
-
 <details>
 <summary>Limitations when using Sanity's GraphQL endpoints</summary>
 
@@ -195,7 +221,7 @@ Note that tags are namespaced within `opt.media` and tag names are accessed via
 #### Deleting assets
 
 <details>
-<summary>How come deleting multiple assets fails, even if only one asset is in use?</summary>
+<summary>Why am I unable to delete multiple assets, even if only one asset is in use?</summary>
 
 - Batch mutations are carried out via Sanity [transactions](https://www.sanity.io/docs/transactions). These transactions are _atomic_, meaning that if one deletion fails (often because it's referenced elsewhere), then all mutations in the transaction will fail and no changes will occur
 - To get around this, simply make sure that all assets you've marked for deletion are not referenced – this can be easily accomplished by using a search facet to only show assets which are not in use
@@ -207,8 +233,8 @@ Note that tags are namespaced within `opt.media` and tag names are accessed via
 <details>
 <summary>How does the plugin determine what should uploaded as a <code>sanity.imageAsset</code> or <code>sanity.fileAsset</code>?</summary>
 
-- The plugin will look at incoming files' MIME type. All files of type `image/*` will be uploaded as `sanity.imageAsset`, everything else will be treated as `sanity.fileAsset`
-- This means that it's not possible to upload images as `sanity.fileAsset` via the plugin. In the rare case that you do need images to be treated as files, consider uploading them outside of the plugin
+- As a rule of thumb, when uploading when accessing the plugin as a _tool_ (e.g. if you've acceessed it via the studio menu), it will look at any incoming files' MIME type. All files of type `image/*` will be uploaded as `sanity.imageAsset` whilst everything else will be treated as `sanity.fileAsset`
+- If you upload when using the plugin in a _file_ selection context, these be uploaded as `sanity.fileAsset` regardless of their MIME type. This is probably not what you want, since images uploaded as files won't have associated metadata nor will they work in Sanity's image pipeline.
 
 </details>
 
@@ -229,3 +255,25 @@ Contributions, issues and feature requests are welcome!
 ## License
 
 MIT. See [license](LICENSE)
+
+## Develop & test
+
+Make sure to run `npm run build` once, then run
+
+```bash
+npm run link-watch
+```
+
+In another shell, `cd` to your test studio and run:
+
+```bash
+npx yalc add sanity-plugin-media && yarn install
+```
+
+Now, changes in this repo will be automatically built and pushed to the studio,
+triggering hotreload. Yalc avoids issues with react-hooks that are typical when using yarn/npm link.
+
+### About build & watch
+
+This plugin uses [@sanity/plugin-sdk](https://github.com/sanity-io/plugin-sdk)
+with default configuration for build & watch scripts.