sanity-plugin-media 4.1.1 → 4.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Sanity.io
+Copyright (c) 2026 Sanity.io
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -95,7 +95,6 @@ export default defineConfig({
 })
 ```
 
-
 ### Plugin Config
 
 ```ts
@@ -111,7 +110,7 @@ export default defineConfig({
         enabled: true,
         // boolean - enables an optional "Credit Line" field in the plugin.
         // Used to store credits e.g. photographer, licence information
-        excludeSources: ['unsplash'],
+        excludeSources: ['unsplash']
         // string | string[] - when used with 3rd party asset sources, you may
         // wish to prevent users overwriting the creditLine based on the `source.name`
       },
@@ -122,13 +121,118 @@ export default defineConfig({
       components: {
         details: CustomDetails
         // Custom component for asset details (see below)
-      }
+      },
       // Custom components to override default UI (see below)
+      locales: [
+        // { id: string, title: string, ...extra }[] - enable localization for asset fields. Each object must have a unique id and a human-readable title.
+        // When set, all localizable fields (title, altText, description, creditLine) will be shown in tabs by language.
+        {id: 'en', title: 'English'},
+        {id: 'it', title: 'Italian'},
+        {id: 'es', title: 'Spanish'},
+        {id: 'fr', title: 'French'},
+        {id: 'de', title: 'German'},
+        {id: 'pt', title: 'Portuguese'},
+        {id: 'ja', title: 'Japanese'},
+        {id: 'zh', title: 'Chinese'},
+        {id: 'ru', title: 'Russian'},
+        {id: 'ar', title: 'Arabic'}
+      ]
     })
+  ]
+})
+```
+
+### Auto-tagging (Optional)
+
+You can automatically apply tags to an asset when it is selected via an image or file field. Import `mediaField` to define a field with both auto-tagging and browser pre-filtering wired up in one call:
+
+```ts
+import {mediaField} from 'sanity-plugin-media'
+
+defineType({
+  name: 'product',
+  type: 'document',
+  fields: [
+    mediaField({
+      name: 'image',
+      type: 'image',
+      mediaTags: ['product'],
+    }),
   ],
 })
 ```
 
+The `mediaTags` array serves double duty: it pre-filters the media browser to show only assets with those tags, and it applies those tags to the asset when one is selected.
+
+For more control, import `AutoTagInput` directly and apply it to individual fields:
+
+```ts
+import {AutoTagInput} from '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']} />,
+  },
+})
+```
+
+By default, tags that don't already exist will be created when an asset is selected. To disable this, set `createTagsOnUpload: false` in the plugin config:
+
+```ts
+media({
+  createTagsOnUpload: false,
+})
+```
+
+### Localization (Optional)
+
+You can enable localization support by passing a `locales` array to the plugin config, following the [Sanity recommended scheme](https://www.sanity.io/docs/studio/localization#k4da239411955):
+
+If omitted, localization features will be disabled and the plugin will work as usual.
+
+**Fallback for missing translations:**
+The plugin does not apply any automatic fallback for missing translations. You can decide how to handle this in your queries or frontend logic. For example, to show the default language if a translation is missing, you can use GROQ's `coalesce()`:
+
+```
+coalesce(altText.it, altText.en)
+```
+
+**UI note:**
+When `locales` are provided, all localized fields (title, altText, description, creditLine) are grouped by language in tabs. Each tab shows all fields for a single language, making it easy to edit translations for many languages in a compact interface.
+
+This will return the Italian value if present, otherwise English, otherwise French, etc. Adjust the order as needed for your project.
+
+#### Migrating existing assets to localized format
+
+If you enable `locales` on a project that already has assets with plain string fields (e.g. `title: "My photo"`), you should run the provided migration script to convert those fields to the localized object format (e.g. `title: {en: "My photo"}`).
+
+**1. Edit the script** — open `scripts/migrate-to-localized-fields.ts` and set `DEFAULT_LOCALE_ID` to the locale id that your existing values should be mapped to.
+
+**2. Run the migration:**
+
+```sh
+npx sanity@latest migration run scripts/migrate-to-localized-fields.ts \
+  --project <projectId> --dataset <dataset>
+```
+
+The script targets `sanity.imageAsset` and `sanity.fileAsset` documents and converts any plain string value in `title`, `altText`, `description`, and `creditLine` to `{[DEFAULT_LOCALE_ID]: value}`. Fields that are already in object format are left untouched.
+
+> **Without migration:** Legacy string fields can also be migrated when an asset is edited and saved in the plugin. Running the script is still recommended to migrate all existing assets consistently before users start editing.
+
+#### Removing locales
+
+If you remove the `locales` option after assets have been saved in localized format, the plugin will show a warning in the asset edit dialog offering a **"Cleanup localized fields"** action. Clicking it removes locale keys that are no longer configured and, if no locales remain, flattens the fields back to plain strings.
+
 #### Custom Asset Details Component
 
 Custom React component for the asset details form via the plugin config. This allows you to override or extend the default asset details UI.

package/dist/index.d.mts

@@ -1,8 +1,12 @@
 import {AssetSourceComponentProps} from 'sanity'
 import type {ComponentType} from 'react'
 import {Control} from 'react-hook-form'
+import type {FieldDefinitionBase} from 'sanity'
 import {FieldErrors} from 'react-hook-form'
+import type {FileDefinition} from 'sanity'
 import {ForwardRefExoticComponent} from 'react'
+import type {ImageDefinition} from 'sanity'
+import {InputProps} from 'sanity'
 import {JSX as JSX_2} from 'react'
 import {Plugin as Plugin_2} from 'sanity'
 import {RefAttributes} from 'react'
@@ -10,17 +14,122 @@ import type {SanityAssetDocument} from '@sanity/client'
 import type {SanityImageAssetDocument} from '@sanity/client'
 import {SVGProps} from 'react'
 import {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
 
-declare type AssetFormData = z.infer<typeof assetFormSchema>
+declare type AssetFormData = z.infer<ReturnType<typeof getAssetFormSchema>>
 
-declare const assetFormSchema: z.ZodObject<
+/**
+ * Input component that automatically applies media tags when an asset is selected or uploaded.
+ *
+ * Apply explicitly to image/file fields that should be auto-tagged:
+ * ```ts
+ * import {AutoTagInput} from 'sanity-plugin-media'
+ *
+ * defineField({
+ *   type: 'image',
+ *   options: { mediaTags: ['product'] },   // also pre-filters the media browser
+ *   components: { input: AutoTagInput },
+ * })
+ * ```
+ *
+ * Pass `mediaTags` as a prop to override or use without `options`:
+ * ```ts
+ * components: { input: (props) => <AutoTagInput {...props} mediaTags={['product']} /> }
+ * ```
+ */
+export declare function AutoTagInput(props: AutoTagInputProps): JSX_2
+
+export declare type AutoTagInputProps = InputProps & {
+  mediaTags?: string[]
+}
+
+declare type CustomFields = {
+  altText?: LocalizedString
+  description?: LocalizedString
+  opt?: {
+    media?: {
+      tags?: SanityReference[]
+    }
+  }
+  title?: LocalizedString
+}
+
+declare type DetailsProps = {
+  formUpdating: boolean
+  handleCreateTag: (title: string) => void
+  control: Control<AssetFormData>
+  errors: FieldErrors<AssetFormData>
+  register: UseFormRegister<AssetFormData>
+  allTagOptions: TagSelectOption[]
+  assetTagOptions: TagSelectOption[] | null
+  currentAsset: Asset
+  creditLine?: {
+    enabled: boolean
+    excludeSources?: string | string[] | undefined
+  }
+  locales?: Locale_2[]
+}
+
+declare type FileAsset = SanityAssetDocument &
+  CustomFields & {
+    _type: 'sanity.fileAsset'
+  }
+
+declare type FileMediaFieldConfig = Omit<FileDefinition, 'options'> &
+  FieldDefinitionBase & {
+    name: string
+    mediaTags: string[]
+    options?: FileDefinition['options']
+  }
+
+declare type FileMediaFieldResult = Omit<FileDefinition, 'options'> &
+  FieldDefinitionBase & {
+    options?: FileDefinition['options'] & {
+      mediaTags: string[]
+    }
+    components: {
+      input: typeof AutoTagInput
+    }
+  } & WidenValidation &
+  WidenInitialValue
+
+declare function getAssetFormSchema(
+  locales?: {
+    id: string
+  }[]
+): z.ZodObject<
   {
-    altText: z.ZodOptional<z.ZodString>
-    creditLine: z.ZodOptional<z.ZodString>
-    description: z.ZodOptional<z.ZodString>
+    altText:
+      | z.ZodOptional<z.ZodString>
+      | z.ZodObject<
+          Record<string, z.ZodTypeAny>,
+          'passthrough',
+          z.ZodTypeAny,
+          z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>,
+          z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+        >
+    creditLine:
+      | z.ZodOptional<z.ZodString>
+      | z.ZodObject<
+          Record<string, z.ZodTypeAny>,
+          'passthrough',
+          z.ZodTypeAny,
+          z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>,
+          z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+        >
+    description:
+      | z.ZodOptional<z.ZodString>
+      | z.ZodObject<
+          Record<string, z.ZodTypeAny>,
+          'passthrough',
+          z.ZodTypeAny,
+          z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>,
+          z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+        >
     opt: z.ZodObject<
       {
         media: z.ZodObject<
@@ -35,12 +144,12 @@ declare const assetFormSchema: z.ZodObject<
                   'strip',
                   z.ZodTypeAny,
                   {
-                    label: string
                     value: string
+                    label: string
                   },
                   {
-                    label: string
                     value: string
+                    label: string
                   }
                 >,
                 'many'
@@ -52,16 +161,16 @@ declare const assetFormSchema: z.ZodObject<
           {
             tags:
               | {
-                  label: string
                   value: string
+                  label: string
                 }[]
               | null
           },
           {
             tags:
               | {
-                  label: string
                   value: string
+                  label: string
                 }[]
               | null
           }
@@ -73,8 +182,8 @@ declare const assetFormSchema: z.ZodObject<
         media: {
           tags:
             | {
-                label: string
                 value: string
+                label: string
               }[]
             | null
         }
@@ -83,15 +192,23 @@ declare const assetFormSchema: z.ZodObject<
         media: {
           tags:
             | {
-                label: string
                 value: string
+                label: string
               }[]
             | null
         }
       }
     >
     originalFilename: z.ZodString
-    title: z.ZodOptional<z.ZodString>
+    title:
+      | z.ZodOptional<z.ZodString>
+      | z.ZodObject<
+          Record<string, z.ZodTypeAny>,
+          'passthrough',
+          z.ZodTypeAny,
+          z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>,
+          z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+        >
   },
   'strip',
   z.ZodTypeAny,
@@ -100,73 +217,92 @@ declare const assetFormSchema: z.ZodObject<
       media: {
         tags:
           | {
-              label: string
               value: string
+              label: string
             }[]
           | null
       }
     }
     originalFilename: string
-    altText?: string | undefined
-    creditLine?: string | undefined
-    description?: string | undefined
-    title?: string | undefined
+    altText?:
+      | string
+      | z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    creditLine?:
+      | string
+      | z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    description?:
+      | string
+      | z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    title?:
+      | string
+      | z.objectOutputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
   },
   {
     opt: {
       media: {
         tags:
           | {
-              label: string
               value: string
+              label: string
             }[]
           | null
       }
     }
     originalFilename: string
-    altText?: string | undefined
-    creditLine?: string | undefined
-    description?: string | undefined
-    title?: string | undefined
+    altText?:
+      | string
+      | z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    creditLine?:
+      | string
+      | z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    description?:
+      | string
+      | z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
+    title?:
+      | string
+      | z.objectInputType<Record<string, z.ZodTypeAny>, z.ZodTypeAny, 'passthrough'>
+      | undefined
   }
 >
 
-declare type CustomFields = {
-  altText?: string
-  description?: string
-  opt?: {
-    media?: {
-      tags?: SanityReference[]
-    }
+declare type ImageAsset = SanityImageAssetDocument &
+  CustomFields & {
+    _type: 'sanity.imageAsset'
+    creditLine?: LocalizedString
   }
-  title?: string
-}
 
-declare type DetailsProps = {
-  formUpdating: boolean
-  handleCreateTag: (title: string) => void
-  control: Control<AssetFormData>
-  errors: FieldErrors<AssetFormData>
-  register: UseFormRegister<AssetFormData>
-  allTagOptions: TagSelectOption[]
-  assetTagOptions: TagSelectOption[] | null
-  currentAsset: Asset
-  creditLine?: {
-    enabled: boolean
-    excludeSources?: string | string[] | undefined
+declare type ImageMediaFieldConfig = Omit<ImageDefinition, 'options'> &
+  FieldDefinitionBase & {
+    name: string
+    mediaTags: string[]
+    options?: ImageDefinition['options']
   }
-}
 
-declare type FileAsset = SanityAssetDocument &
-  CustomFields & {
-    _type: 'sanity.fileAsset'
-  }
+declare type ImageMediaFieldResult = Omit<ImageDefinition, 'options'> &
+  FieldDefinitionBase & {
+    options?: ImageDefinition['options'] & {
+      mediaTags: string[]
+    }
+    components: {
+      input: typeof AutoTagInput
+    }
+  } & WidenValidation &
+  WidenInitialValue
 
-declare type ImageAsset = SanityImageAssetDocument &
-  CustomFields & {
-    _type: 'sanity.imageAsset'
-    creditLine?: string
-  }
+declare type Locale_2 = {
+  title: string
+  id: string
+  [key: string]: unknown
+}
+
+declare type LocalizedString = string | Record<string, string>
 
 export declare const media: Plugin_2<void | MediaToolOptions>
 
@@ -179,8 +315,38 @@ export declare const mediaAssetSource: {
   title: string
 }
 
+/**
+ * Defines an image or file field with automatic media tag application when an asset is selected.
+ *
+ * Pass `mediaTags` at the top level — they are moved into `options.mediaTags` (for media browser
+ * pre-filtering) and wire up {@link AutoTagInput} as the field component automatically:
+ * ```ts
+ * import {mediaField} from 'sanity-plugin-media'
+ *
+ * mediaField({
+ *   name: 'coverImage',
+ *   type: 'image',
+ *   mediaTags: ['product-cover'],
+ *   options: { hotspot: true },
+ * })
+ * ```
+ *
+ * For file fields, set `type: 'file'`:
+ * ```ts
+ * mediaField({ name: 'drawing', type: 'file', mediaTags: ['model-drawing'] })
+ * ```
+ */
+export declare function mediaField(config: ImageMediaFieldConfig): ImageMediaFieldResult
+
+export declare function mediaField(config: FileMediaFieldConfig): FileMediaFieldResult
+
+export declare type MediaTagsOptions = {
+  mediaTags?: string[]
+}
+
 export declare type MediaToolOptions = {
   maximumUploadSize?: number
+  createTagsOnUpload?: boolean
   components?: {
     details?: ComponentType<
       DetailsProps & {
@@ -188,11 +354,16 @@ export declare type MediaToolOptions = {
       }
     >
   }
-  creditLine: {
+  creditLine?: {
     enabled: boolean
     excludeSources?: string | string[]
   }
   directUploads?: boolean
+  /**
+   * Optional locales following Sanity recommended scheme: [{ id, title }]
+   * https://www.sanity.io/docs/studio/localization#k4da239411955
+   */
+  locales?: Locale_2[]
 }
 
 declare type SanityReference = {
@@ -209,12 +380,12 @@ declare const tagOptionSchema: z.ZodObject<
   'strip',
   z.ZodTypeAny,
   {
-    label: string
     value: string
+    label: string
   },
   {
-    label: string
     value: string
+    label: string
   }
 >