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

package/README.md

@@ -1,9 +1,16 @@
-# Sanity Media Plugin - Electrolux Version (for Sanity Studio v4)
+# Sanity Media Plugin - Electrolux Version (for Sanity Studio v5 and v6)
 
-> This plugin is for **Sanity Studio v4**.  
+> 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)
 
-## :warning: Breaking changes - (v2.0.0 → v3.0.0)
+## :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**.  
@@ -11,7 +18,7 @@ Projects using this plugin must update to React 19 before upgrading to v3.
 
 ## What is it?
 
-A Sanity Studio v4 plugin that extends media handling capabilities with custom enhancements, based on a fork of an original plugin by Sanity.io.
+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.
 
 A convenient way to browse, manage and refine your [Sanity](https://www.sanity.io/) assets.
 
@@ -20,11 +27,9 @@ Use it standalone as a browser, or optionally hook it up as a [custom asset sour
 ![Grid view](https://user-images.githubusercontent.com/209129/108927411-21aa7f00-7638-11eb-9cf7-334598ac4103.png)
 _Default grid view_
 
-
-_Asset details tab_          |  _Asset alt texts tab_
-:-------------------------:|:-------------------------:
-![first](https://github.com/user-attachments/assets/477b6576-a1a4-42e2-b2c2-2d2e962eb366)  |  ![second](https://github.com/user-attachments/assets/2c5bd907-1b60-48c6-a007-2f7304409007)
-
+|                                    _Asset details tab_                                    |                                   _Asset alt texts tab_                                    |
+| :---------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------: |
+| ![first](https://github.com/user-attachments/assets/477b6576-a1a4-42e2-b2c2-2d2e962eb366) | ![second](https://github.com/user-attachments/assets/2c5bd907-1b60-48c6-a007-2f7304409007) |
 
 ## Features
 
@@ -58,18 +63,18 @@ _Asset details tab_          |  _Asset alt texts tab_
 - 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).
 
-## Install (Sanity Studio v4)
+## Install (Sanity Studio v5 and v6)
 
 In your Sanity project folder:
 
 ```zsh
-npm install --save sanity-plugin-media
+npm install --save @electrolux-oss/sanity-plugin-media
 ```
 
 or
 
 ```zsh
-yarn add sanity-plugin-media
+yarn add @electrolux-oss/sanity-plugin-media
 ```
 
 ## Usage
@@ -77,19 +82,19 @@ yarn add sanity-plugin-media
 Add it as a plugin in your `sanity.config.ts` (or .js) file:
 
 ```js
-import { media } from 'sanity-plugin-media'
+import { media } from '@electrolux-oss/sanity-plugin-media'
 
 export default defineConfig({
   // ...
   plugins: [
-    media(      
+    media({
       languages: [
         { code: 'en-US', title: 'English', default: true },
         { code: 'sv-SE', title: 'Swedish' },
         { code: 'fr-FR', title: 'French' },
         { code: 'de-DE', title: 'German' }
-      ],
-    )
+      ]
+    })
   ]
 })
 ```
@@ -101,7 +106,7 @@ This will enable the Media plugin as both a standalone tool (accessible in your
 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).
 
 ```js
-import { media, mediaAssetSource } from 'sanity-plugin-media'
+import { media, mediaAssetSource } from '@electrolux-oss/sanity-plugin-media'
 
 export default defineConfig({
   // ...
@@ -110,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
+        )
       }
     }
   }
@@ -126,7 +133,7 @@ export default defineConfig({
   plugins: [
     media({
       // { code: string; title: string, default?: boolean }[] - the list of languages used for alt texts
-      // NOTE! Set only one language to default: true. 
+      // NOTE! Set only one language to default: true.
       languages: [
         { code: 'en-US', title: 'English', default: true },
         { code: 'sv-SE', title: 'Swedish' },
@@ -137,17 +144,85 @@ 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`
       },
-      maximumUploadSize: 10000000
-      // number - maximum file size (in bytes) that can be uploaded through the plugin interface
+      maximumUploadSize: 10000000,
+      // 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
+      }
     })
-  ],
+  ]
 })
 ```
 
+### 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
@@ -155,17 +230,20 @@ export default defineConfig({
 **Step 1: Set up the plugin for local development**
 
 In the plugin directory, run:
+
 ```zsh
 npm run link-watch
 ```
 
 This will:
+
 - Build your plugin automatically whenever code changes
 - Publish the package to a local yalc repository
 
 **Step 2: Link the plugin to your studio**
 
 In your studio project directory, run:
+
 ```zsh
 npx yalc add @electrolux-oss/sanity-plugin-media && npm install
 ```
@@ -173,18 +251,21 @@ npx yalc add @electrolux-oss/sanity-plugin-media && npm install
 **Step 3: Verify the setup**
 
 Check your studio's `package.json` - you should see:
+
 ```json
 "@electrolux-oss/sanity-plugin-media": "file:.yalc/@electrolux-oss/sanity-plugin-media"
 ```
 
 Now you can use the local version of the plugin:
+
 ```typescript
-import { workflow } from '@electrolux-oss/sanity-plugin-media'
+import { media } from '@electrolux-oss/sanity-plugin-media'
 ```
 
 ### Making changes
 
 When you modify the plugin code:
+
 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`

package/dist/index.d.ts

@@ -1,14 +1,213 @@
 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'
+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
+
+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>
+        >
+    creditLine: z.ZodOptional<z.ZodString>
+    description: z.ZodOptional<z.ZodString>
+    opt: z.ZodObject<
+      {
+        media: z.ZodObject<
+          {
+            tags: z.ZodNullable<
+              z.ZodArray<
+                z.ZodObject<
+                  {
+                    label: z.ZodString
+                    value: z.ZodString
+                  },
+                  'strip',
+                  z.ZodTypeAny,
+                  {
+                    label: string
+                    value: string
+                  },
+                  {
+                    label: string
+                    value: string
+                  }
+                >,
+                'many'
+              >
+            >
+          },
+          'strip',
+          z.ZodTypeAny,
+          {
+            tags:
+              | {
+                  label: string
+                  value: string
+                }[]
+              | null
+          },
+          {
+            tags:
+              | {
+                  label: string
+                  value: string
+                }[]
+              | null
+          }
+        >
+      },
+      'strip',
+      z.ZodTypeAny,
+      {
+        media: {
+          tags:
+            | {
+                label: string
+                value: string
+              }[]
+            | null
+        }
+      },
+      {
+        media: {
+          tags:
+            | {
+                label: string
+                value: string
+              }[]
+            | null
+        }
+      }
+    >
+    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
+  }
+>
+
+declare type CustomFields = {
+  altText?: string
+  altTexts?: Record<string, string>
+  description?: string
+  opt?: {
+    media?: {
+      tags?: SanityReference[]
+      uploadedBy?: Uploader | string
+    }
+  }
+  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 FileAsset = SanityAssetDocument &
+  CustomFields & {
+    _type: 'sanity.fileAsset'
+  }
+
+declare type ImageAsset = SanityImageAssetDocument &
+  CustomFields & {
+    _type: 'sanity.imageAsset'
+    creditLine?: string
+  }
 
 export declare const media: Plugin_2<void | MediaToolOptions>
 
 export declare const mediaAssetSource: {
-  component: (props: AssetSourceComponentProps) => JSX.Element
+  component: (props: AssetSourceComponentProps) => JSX
+  uploadMode: 'component'
   icon: ForwardRefExoticComponent<
     Omit<SVGProps<SVGSVGElement>, 'ref'> & RefAttributes<SVGSVGElement>
   >
@@ -16,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
@@ -23,10 +258,64 @@ export declare type MediaToolOptions = {
     default?: boolean
   }[]
   maximumUploadSize?: number
+  createTagsOnUpload?: boolean
+  components?: {
+    details?: ComponentType<
+      DetailsProps & {
+        renderDefaultDetails: (props: DetailsProps) => JSX.Element
+      }
+    >
+  }
   creditLine: {
     enabled: boolean
     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 = {
+  _ref: string
+  _type: 'reference'
+  _weak?: boolean
+}
+
+declare const tagOptionSchema: z.ZodObject<
+  {
+    label: z.ZodString
+    value: z.ZodString
+  },
+  'strip',
+  z.ZodTypeAny,
+  {
+    label: string
+    value: string
+  },
+  {
+    label: string
+    value: string
+  }
+>
+
+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[]
+  }
+}