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

package/README.md

@@ -115,7 +115,9 @@ 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
+        )
       }
     }
   }
@@ -147,9 +149,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,6 +171,58 @@ 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

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,6 +24,19 @@ 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
@@ -152,6 +171,7 @@ declare type CustomFields = {
   opt?: {
     media?: {
       tags?: SanityReference[]
+      uploadedBy?: Uploader | string
     }
   }
   title?: string
@@ -195,6 +215,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 +258,7 @@ export declare type MediaToolOptions = {
     default?: boolean
   }[]
   maximumUploadSize?: number
+  createTagsOnUpload?: boolean
   components?: {
     details?: ComponentType<
       DetailsProps & {
@@ -214,6 +271,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 = {
@@ -241,4 +305,17 @@ declare const tagOptionSchema: z.ZodObject<
 
 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[]
+  }
+}