@electrolux-oss/sanity-plugin-media 4.0.0 → 5.0.0

package/README.md

@@ -1,28 +1,14 @@
-# Sanity Media Plugin - Electrolux Version (for Sanity Studio v5 and v6)
+# Sanity Media Plugin - Electrolux Version (for Sanity Studio v6)
 
-> This plugin supports **Sanity Studio v5 and v6**.  
-> This is a forked version of Sanitys own [Media Plugin (v4.0.0)](https://github.com/sanity-io/sanity-plugin-media)
+> This plugin supports **Sanity Studio v6.20 and newer**.
+> Originally based on Sanity's [sanity-io/sanity-plugin-media](https://github.com/sanity-io/sanity-plugin-media) (v4.0.0, MIT).
 
-## :warning: Breaking changes - (v3.0.0 → v4.0.0)
-
-### **v3 → v4**
-
-This release targets **Sanity Studio v5 and v6**. Support for Studio v4 has been dropped, and the
-package is now **ESM-only** (the CommonJS build has been removed).  
-Projects must be on Studio v5 or v6 (and React 19.2.2 or newer) before upgrading to v4.
-
-### **v2 → v3**
-
-This release upgrades the plugin’s peer dependency from **React 18** to **React 19**.  
-Projects using this plugin must update to React 19 before upgrading to v3.
-
-## What is it?
-
-A Sanity Studio v5 / v6 plugin that extends media handling capabilities with custom enhancements, based on a fork of an original plugin by Sanity.io.
+> [!WARNING]
+> Breaking changes introduced in version 5.0.0 of this plugin. See [Breaking changes](#breaking-changes).
 
 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 both image and file selection too.
+Use it standalone as a browser, or hook it up as a [custom asset source](https://www.sanity.io/docs/custom-asset-sources) to power both image and file selection too.
 
 ![Grid view](https://user-images.githubusercontent.com/209129/108927411-21aa7f00-7638-11eb-9cf7-334598ac4103.png)
 _Default grid view_
@@ -58,14 +44,24 @@ _Default grid view_
 - Built with the same [UI components Sanity uses](https://www.sanity.io/ui) under the hood
 - Fully responsive and mobile friendly
 
-#### Added support for multi-language alt texts
+#### Electrolux additions
 
-- Define a list of available languages to enable multi-language alt texts for assets.
-- See example of how to enable this feature [here](###plugin-config).
+- Multi-language alt texts, with validation of the default language (see [Plugin config](#plugin-config))
+- Automatic tagging of assets selected or uploaded through a field (see [Auto-tagging assets from a field](#auto-tagging-assets-from-a-field))
+- An **Edit Media** option on image and file fields (see [Edit Media](#edit-media))
+- A maximum upload size for every upload in the Studio, and tags that hide assets from the browser
+- A record of who uploaded each asset (see [Uploaded by](#uploaded-by))
 
-## Install (Sanity Studio v5 and v6)
+## Install (Sanity Studio v6.20+)
 
-In your Sanity project folder:
+| Package / Runtime     | Requirement |
+| --------------------- | ----------- |
+| `sanity`              | `^6.20.0`   |
+| `react` / `react-dom` | `^19.2.2`   |
+| `styled-components`   | `^6.1.15`   |
+| Node.js               | `>=22.12`   |
+
+Run
 
 ```zsh
 npm install --save @electrolux-oss/sanity-plugin-media
@@ -115,14 +111,16 @@ export default defineConfig({
     // 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)
+        return previousAssetSources.filter(
+          assetSource => assetSource.name !== mediaAssetSource.name
+        )
       }
     }
   }
 })
 ```
 
-### Plugin Config
+### Plugin config
 
 ```ts
 // sanity.config.ts
@@ -147,9 +145,20 @@ export default defineConfig({
         // wish to prevent users overwriting the creditLine based on the `source.name`
       },
       maximumUploadSize: 10000000,
-      // number - maximum file size (in bytes) that can be uploaded through the plugin interface
+      // number - maximum file size (in bytes) for uploads, both through the plugin interface and
+      // through the image / file fields' own upload button (any upload-capable asset source)
       directUploads: true,
       // boolean - enable / disable direct uploads through the plugin interface (default true)
+      createTagsOnUpload: true,
+      // boolean - create tags listed in a field's `mediaTags` if they don't exist yet (default true)
+      uploadMenu: false,
+      // boolean - offer "Media" as an upload target in image / file fields (default true).
+      // Set to false to make the upload button use the workspace's own uploader directly;
+      // "Media" is then only listed under "Select"
+      excludeTags: ['internal', 'archived'],
+      // string[] (optional) - tag slugs (`media.tag` `name.current`). Assets with any of these
+      // tags are hidden from the Media browser and asset picker, and the tags themselves are
+      // hidden in the tag panel and tag search facet. The asset edit dialog still lists all tags.
       components: {
         details: CustomDetails
       }
@@ -158,9 +167,61 @@ export default defineConfig({
 })
 ```
 
+### Auto-tagging assets from a field
+
+Assets selected or uploaded through a field can be tagged automatically. The same tags pre-filter the media browser when it is opened from that field.
+
+```ts
+import { mediaField } from '@electrolux-oss/sanity-plugin-media'
+
+defineType({
+  name: 'product',
+  type: 'document',
+  fields: [
+    mediaField({
+      name: 'image',
+      type: 'image',
+      mediaTags: ['product']
+    })
+  ]
+})
+```
+
+Or use the input component directly:
+
+```tsx
+import { AutoTagInput } from '@electrolux-oss/sanity-plugin-media'
+
+defineField({
+  name: 'image',
+  type: 'image',
+  options: { mediaTags: ['product'] }, // pre-filters the browser
+  components: { input: AutoTagInput } // applies tags on select
+})
+
+// Or pass mediaTags as a prop to override the field options:
+defineField({
+  name: 'image',
+  type: 'image',
+  components: {
+    input: props => <AutoTagInput {...props} mediaTags={['product']} />
+  }
+})
+```
+
+Only assets selected after the document is opened are tagged. Existing values are left untouched. Tags missing from the dataset are created unless `createTagsOnUpload` is `false`.
+
+### Uploaded by
+
+The asset details panel shows who uploaded an asset. It is recorded as `opt.media.uploadedBy` (`{ id }`, the Sanity user ID only; the sync button next to it fetches the person's name, and email when Sanity returns it, on demand) when a logged-in user uploads through the Studio: in the Media browser, or with an image / file field's own upload button and drag and drop. Only uploads made in that user's browser are recorded, so collaborators editing the same document are never credited. Assets uploaded by scripts, the CLI, API tokens or before this feature existed show **Unknown**.
+
+### Edit Media
+
+The plugin adds an **Edit Media** option to the asset menu of image and file fields. It opens the edit dialog (title, alt texts, description, tags, …) for the field's current asset, without leaving the document.
+
 ## Develop locally
 
-### Test your plugin locally
+### Link the plugin to a local studio
 
 **Step 1: Set up the plugin for local development**
 
@@ -199,8 +260,57 @@ import { media } from '@electrolux-oss/sanity-plugin-media'
 
 ### Making changes
 
-When you modify the plugin code:
+When you modify the plugin code, `link-watch` rebuilds it and pushes the build to every studio
+linked with yalc. Reload the studio to pick up the changes, and restart its dev server if it still
+serves the old build.
+
+### Running the checks
+
+```zsh
+npm run typecheck # tsc --noEmit
+npm run lint      # ESLint
+npm run build     # also fails on type errors
+```
+
+This plugin has no automated tests yet.
+
+## Breaking changes
+
+### **v4 → v5**
+
+This release requires **Sanity Studio v6.20 or newer**, the first Studio release on `@sanity/ui`
+^4.4.9. Support for Studio v5 and Studio v6 before 6.20 has been dropped; stay on v4 of this
+plugin for older Studios.
 
-1. The `link-watch` command will automatically rebuild
-2. In your studio, run `npx yalc update` to pull the latest changes
-3. Restart your dev server: `npm run dev`
+- The plugin now uses the same `@sanity/ui` (v4) and `@sanity/client` (v8) versions as the Studio,
+  so npm installs one shared copy of each instead of a second one inside the plugin.
+- `react-is` is no longer a peer dependency.
+- The tag inputs take their colors and fonts from the Studio's theme, so they follow custom themes.
+
+Requirements:
+
+| Package / Runtime     | Requirement |
+| --------------------- | ----------- |
+| `sanity`              | `^6.20.0`   |
+| `react` / `react-dom` | `^19.2.2`   |
+| `styled-components`   | `^6.1.15`   |
+| Node.js               | `>=22.12`   |
+
+### **v3 → v4**
+
+This release targets **Sanity Studio v5 and v6**. Support for Studio v4 has been dropped, and the
+package is now **ESM-only** (the CommonJS build has been removed).
+
+Requirements:
+
+| Package / Runtime                  | Requirement          |
+| ---------------------------------- | -------------------- |
+| `sanity`                           | `^5.0.0 \|\| ^6.0.0` |
+| `react` / `react-dom` / `react-is` | `^19.2.2`            |
+| `styled-components`                | `^6.1.15`            |
+| Node.js                            | `>=22.12`            |
+
+### **v2 → v3**
+
+This release upgrades the plugin’s peer dependency from **React 18** to **React 19**.  
+Projects using this plugin must update to React 19 before upgrading to v3.

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 import { AssetSourceComponentProps } from 'sanity'
 import type { ComponentType } from 'react'
 import type { Control } from 'react-hook-form'
+import type { FieldDefinitionBase } from 'sanity'
 import type { FieldErrors } from 'react-hook-form'
+import type { FileDefinition } from 'sanity'
 import { ForwardRefExoticComponent } from 'react'
+import type { ImageDefinition } from 'sanity'
+import type { InputProps } from 'sanity'
 import { JSX } from 'react'
 import { Plugin as Plugin_2 } from 'sanity'
 import { RefAttributes } from 'react'
@@ -10,6 +14,8 @@ import type { SanityAssetDocument } from '@sanity/client'
 import type { SanityImageAssetDocument } from '@sanity/client'
 import { SVGProps } from 'react'
 import type { UseFormRegister } from 'react-hook-form'
+import type { WidenInitialValue } from 'sanity'
+import type { WidenValidation } from 'sanity'
 import * as z from 'zod'
 
 declare type Asset = FileAsset | ImageAsset
@@ -18,19 +24,26 @@ declare type AssetFormData = z.infer<AssetFormSchemaObject>
 
 declare type AssetFormSchemaObject = ReturnType<typeof createAssetFormSchema>
 
+/**
+ * Image / file input that tags the selected or uploaded asset with `mediaTags`.
+ *
+ * Tags come from the `mediaTags` prop, falling back to `options.mediaTags` on the field
+ * (which also pre-filters the media browser). Only changes made after mount are tagged,
+ * so opening a document never patches its existing assets.
+ */
+export declare function AutoTagInput(props: AutoTagInputProps): JSX
+
+export declare type AutoTagInputProps = InputProps & {
+  mediaTags?: string[]
+}
+
 declare const createAssetFormSchema: (
   languages: MediaToolOptions['languages'],
   validateAltTexts?: boolean
 ) => z.ZodObject<
   {
     altText: z.ZodOptional<z.ZodString>
-    altTexts:
-      | z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>
-      | z.ZodEffects<
-          z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>,
-          Record<string, string | null>,
-          Record<string, string | null>
-        >
+    altTexts: z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>
     creditLine: z.ZodOptional<z.ZodString>
     description: z.ZodOptional<z.ZodString>
     opt: z.ZodObject<
@@ -44,105 +57,20 @@ declare const createAssetFormSchema: (
                     label: z.ZodString
                     value: z.ZodString
                   },
-                  'strip',
-                  z.ZodTypeAny,
-                  {
-                    label: string
-                    value: string
-                  },
-                  {
-                    label: string
-                    value: string
-                  }
-                >,
-                'many'
+                  z.core.$strip
+                >
               >
             >
           },
-          'strip',
-          z.ZodTypeAny,
-          {
-            tags:
-              | {
-                  label: string
-                  value: string
-                }[]
-              | null
-          },
-          {
-            tags:
-              | {
-                  label: string
-                  value: string
-                }[]
-              | null
-          }
+          z.core.$strip
         >
       },
-      'strip',
-      z.ZodTypeAny,
-      {
-        media: {
-          tags:
-            | {
-                label: string
-                value: string
-              }[]
-            | null
-        }
-      },
-      {
-        media: {
-          tags:
-            | {
-                label: string
-                value: string
-              }[]
-            | null
-        }
-      }
+      z.core.$strip
     >
     originalFilename: z.ZodString
     title: z.ZodOptional<z.ZodString>
   },
-  'strip',
-  z.ZodTypeAny,
-  {
-    altTexts: Record<string, string | null>
-    opt: {
-      media: {
-        tags:
-          | {
-              label: string
-              value: string
-            }[]
-          | null
-      }
-    }
-    originalFilename: string
-    altText?: string | undefined
-    creditLine?: string | undefined
-    description?: string | undefined
-    title?: string | undefined
-  },
-  {
-    altTexts: Record<string, string | null>
-    opt: {
-      media: {
-        tags:
-          | {
-              label: string
-              value: string
-            }[]
-          | null
-      }
-    }
-    originalFilename: string
-    altText?: string | undefined
-    creditLine?: string | undefined
-    description?: string | undefined
-    title?: string | undefined
-  }
+  z.core.$strip
 >
 
 declare type CustomFields = {
@@ -152,6 +80,7 @@ declare type CustomFields = {
   opt?: {
     media?: {
       tags?: SanityReference[]
+      uploadedBy?: Uploader | string
     }
   }
   title?: string
@@ -195,6 +124,42 @@ export declare const mediaAssetSource: {
   title: string
 }
 
+/**
+ * Defines an image or file field whose selected / uploaded assets are tagged with `mediaTags`.
+ *
+ * `mediaTags` is copied to `options.mediaTags` (which pre-filters the media browser) and
+ * {@link AutoTagInput} is set as the input component.
+ *
+ * ```ts
+ * mediaField({ name: 'image', type: 'image', mediaTags: ['product'] })
+ * ```
+ */
+export declare function mediaField(
+  config: MediaFieldConfig<ImageDefinition>
+): MediaFieldResult<ImageDefinition>
+
+export declare function mediaField(
+  config: MediaFieldConfig<FileDefinition>
+): MediaFieldResult<FileDefinition>
+
+declare type MediaFieldConfig<T extends ImageDefinition | FileDefinition> = Omit<T, 'options'> &
+  FieldDefinitionBase & {
+    name: string
+    mediaTags: string[]
+    options?: T['options']
+  }
+
+declare type MediaFieldResult<T extends ImageDefinition | FileDefinition> = Omit<T, 'options'> &
+  FieldDefinitionBase & {
+    options?: T['options'] & {
+      mediaTags: string[]
+    }
+    components: {
+      input: typeof AutoTagInput
+    }
+  } & WidenValidation &
+  WidenInitialValue
+
 export declare type MediaToolOptions = {
   languages: {
     code: string
@@ -202,6 +167,7 @@ export declare type MediaToolOptions = {
     default?: boolean
   }[]
   maximumUploadSize?: number
+  createTagsOnUpload?: boolean
   components?: {
     details?: ComponentType<
       DetailsProps & {
@@ -214,6 +180,13 @@ export declare type MediaToolOptions = {
     excludeSources?: string | string[]
   }
   directUploads?: boolean
+  uploadMenu?: boolean
+  /**
+   * Tag slugs (`media.tag` `name.current`) whose assets are hidden from the Media browser and
+   * asset picker, along with the tags themselves in the tag panel and tag search facet.
+   * The asset edit dialog still lists every tag.
+   */
+  excludeTags?: string[]
 }
 
 declare type SanityReference = {
@@ -227,18 +200,22 @@ declare const tagOptionSchema: z.ZodObject<
     label: z.ZodString
     value: z.ZodString
   },
-  'strip',
-  z.ZodTypeAny,
-  {
-    label: string
-    value: string
-  },
-  {
-    label: string
-    value: string
-  }
+  z.core.$strip
 >
 
 declare type TagSelectOption = z.infer<typeof tagOptionSchema>
 
+declare type Uploader = {
+  id: string
+  /** Only set by earlier builds; the name is now looked up on demand. */
+  name?: string
+}
+
 export {}
+
+declare module 'sanity' {
+  interface FileOptions {
+    /** Tags applied by `AutoTagInput` / `mediaField`, also used to pre-filter the media browser. */
+    mediaTags?: string[]
+  }
+}