sanity-plugin-media 4.2.0 → 4.3.1

package/README.md

@@ -142,6 +142,58 @@ export default defineConfig({
 })
 ```
 
+### 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):

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,12 +14,39 @@ 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<ReturnType<typeof getAssetFormSchema>>
 
+/**
+ * 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
@@ -48,6 +79,24 @@ declare type FileAsset = SanityAssetDocument &
     _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
@@ -229,6 +278,24 @@ declare type ImageAsset = SanityImageAssetDocument &
     creditLine?: LocalizedString
   }
 
+declare type ImageMediaFieldConfig = Omit<ImageDefinition, 'options'> &
+  FieldDefinitionBase & {
+    name: string
+    mediaTags: string[]
+    options?: ImageDefinition['options']
+  }
+
+declare type ImageMediaFieldResult = Omit<ImageDefinition, 'options'> &
+  FieldDefinitionBase & {
+    options?: ImageDefinition['options'] & {
+      mediaTags: string[]
+    }
+    components: {
+      input: typeof AutoTagInput
+    }
+  } & WidenValidation &
+  WidenInitialValue
+
 declare type Locale_2 = {
   title: string
   id: string
@@ -248,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 & {

package/dist/index.d.ts

@@ -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,12 +14,39 @@ 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<ReturnType<typeof getAssetFormSchema>>
 
+/**
+ * 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
@@ -48,6 +79,24 @@ declare type FileAsset = SanityAssetDocument &
     _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
@@ -229,6 +278,24 @@ declare type ImageAsset = SanityImageAssetDocument &
     creditLine?: LocalizedString
   }
 
+declare type ImageMediaFieldConfig = Omit<ImageDefinition, 'options'> &
+  FieldDefinitionBase & {
+    name: string
+    mediaTags: string[]
+    options?: ImageDefinition['options']
+  }
+
+declare type ImageMediaFieldResult = Omit<ImageDefinition, 'options'> &
+  FieldDefinitionBase & {
+    options?: ImageDefinition['options'] & {
+      mediaTags: string[]
+    }
+    components: {
+      input: typeof AutoTagInput
+    }
+  } & WidenValidation &
+  WidenInitialValue
+
 declare type Locale_2 = {
   title: string
   id: string
@@ -248,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 & {