sanity-plugin-media 4.1.1 → 4.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sanity-plugin-media",
-  "version": "4.1.1",
+  "version": "4.3.0",
   "description": "This version of `sanity-plugin-media` is for Sanity Studio V3.",
   "keywords": [
     "sanity",
@@ -48,6 +48,8 @@
     "format": "prettier --write --cache --ignore-unknown .",
     "link-watch": "plugin-kit link-watch",
     "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepare": "husky install",
     "prepublishOnly": "npm run build",
     "watch": "pkg-utils watch --strict"
@@ -87,6 +89,9 @@
     "@sanity/plugin-kit": "^4.0.19",
     "@sanity/semantic-release-preset": "^2.0.5",
     "@sanity/vision": "^3.80.1",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.2.0",
+    "@testing-library/user-event": "^14.6.1",
     "@types/is-hotkey": "^0.1.10",
     "@types/pluralize": "^0.0.33",
     "@types/react": "^19.0.12",
@@ -102,6 +107,7 @@
     "eslint-plugin-react": "^7.37.4",
     "eslint-plugin-react-hooks": "^4.6.2",
     "husky": "^8.0.2",
+    "jsdom": "^25.0.1",
     "lint-staged": "^13.0.3",
     "prettier": "^2.8.8",
     "prettier-plugin-packagejson": "^2.5.10",
@@ -112,7 +118,8 @@
     "sanity": "^3.80.1",
     "standard-version": "^9.5.0",
     "styled-components": "^6.1.16",
-    "typescript": "5.8.2"
+    "typescript": "5.8.2",
+    "vitest": "^3.0.5"
   },
   "peerDependencies": {
     "react": "^18.3 || ^19",

package/src/__tests__/fixtures/createEpicTestStore.ts

@@ -0,0 +1,27 @@
+import {configureStore, type AnyAction, type EnhancedStore} from '@reduxjs/toolkit'
+import type {SanityClient} from '@sanity/client'
+import type {Epic} from 'redux-observable'
+import {createEpicMiddleware} from 'redux-observable'
+import {rootReducer} from '../../modules'
+import type {RootReducerState} from '../../modules/types'
+import {createTestRootState} from './rootState'
+
+export function createEpicTestStore(
+  epic: Epic<AnyAction, AnyAction, RootReducerState, {client: SanityClient}>,
+  mockClient: SanityClient,
+  preloaded?: Partial<RootReducerState>
+): EnhancedStore<RootReducerState, AnyAction> {
+  const epicMiddleware = createEpicMiddleware<AnyAction, AnyAction, RootReducerState>({
+    dependencies: {client: mockClient}
+  })
+
+  const store = configureStore({
+    reducer: rootReducer,
+    middleware: getDefaultMiddleware =>
+      getDefaultMiddleware({serializableCheck: false, thunk: false}).concat(epicMiddleware),
+    preloadedState: createTestRootState(preloaded)
+  })
+
+  epicMiddleware.run(epic)
+  return store
+}

package/src/__tests__/fixtures/listenMock.ts

@@ -0,0 +1,9 @@
+import {vi} from 'vitest'
+
+/** Flat mock for client.listen() without deep callback nesting (ESLint max-nested-callbacks). */
+export function createListenMock(): ReturnType<typeof vi.fn> {
+  const unsubscribe = vi.fn()
+  const subscribe = vi.fn()
+  subscribe.mockReturnValue({unsubscribe})
+  return vi.fn().mockReturnValue({subscribe})
+}

package/src/__tests__/fixtures/mockSanityClient.ts

@@ -0,0 +1,84 @@
+import type {SanityClient} from '@sanity/client'
+import {Subject, of} from 'rxjs'
+import {vi} from 'vitest'
+
+export type MockSanityClient = {
+  observable: {
+    fetch: ReturnType<typeof vi.fn>
+    delete: ReturnType<typeof vi.fn>
+    create: ReturnType<typeof vi.fn>
+    assets: {upload: ReturnType<typeof vi.fn>}
+  }
+  fetch: ReturnType<typeof vi.fn>
+  listen: ReturnType<typeof vi.fn>
+  patch: ReturnType<typeof vi.fn>
+  transaction: ReturnType<typeof vi.fn>
+}
+
+export function createMockSanityClient(
+  overrides: Partial<Omit<MockSanityClient, 'observable'>> & {
+    observable?: Partial<MockSanityClient['observable']> & {
+      assets?: Partial<MockSanityClient['observable']['assets']>
+    }
+  } = {}
+): SanityClient {
+  const {observable: observableOverrides, ...restOverrides} = overrides
+
+  const observableBase: MockSanityClient['observable'] = {
+    fetch: vi.fn(() => of({items: []})),
+    delete: vi.fn(() => of({})),
+    create: vi.fn(() => of({_id: 'new'})),
+    assets: {
+      upload: vi.fn(() => of({type: 'complete', body: {document: {_id: 'up'}}}))
+    }
+  }
+
+  const observable: MockSanityClient['observable'] = {
+    ...observableBase,
+    ...(observableOverrides ?? {}),
+    assets: {
+      ...observableBase.assets,
+      ...(observableOverrides?.assets ?? {})
+    }
+  }
+
+  const client: MockSanityClient = {
+    observable,
+    fetch: vi.fn(() => Promise.resolve(0)),
+    listen: vi.fn(() => new Subject()),
+    patch: vi.fn(),
+    transaction: vi.fn(),
+    ...restOverrides
+  }
+
+  return client as unknown as SanityClient
+}
+
+export function mockPatchChain(result: unknown): {
+  set: ReturnType<typeof vi.fn>
+  setIfMissing: ReturnType<typeof vi.fn>
+  commit: ReturnType<typeof vi.fn>
+} {
+  const commit = vi.fn().mockResolvedValue(result)
+  const chain = {
+    set: vi.fn(),
+    setIfMissing: vi.fn(),
+    commit
+  }
+  chain.set.mockImplementation(() => chain)
+  chain.setIfMissing.mockImplementation(() => chain)
+  return chain
+}
+
+export function mockTransactionCommit(resolved: unknown = undefined): {
+  patch: ReturnType<typeof vi.fn>
+  delete: ReturnType<typeof vi.fn>
+  commit: ReturnType<typeof vi.fn>
+} {
+  const tx = {
+    patch: vi.fn().mockReturnThis(),
+    delete: vi.fn().mockReturnThis(),
+    commit: vi.fn().mockResolvedValue(resolved)
+  }
+  return tx
+}

package/src/__tests__/fixtures/renderWithProviders.tsx

@@ -0,0 +1,54 @@
+import type {ReactElement, ReactNode} from 'react'
+import {configureStore} from '@reduxjs/toolkit'
+import {studioTheme, ThemeProvider, ToastProvider} from '@sanity/ui'
+import {ColorSchemeProvider} from 'sanity'
+import {Provider} from 'react-redux'
+import {render} from '@testing-library/react'
+import {AssetBrowserDispatchProvider} from '../../contexts/AssetSourceDispatchContext'
+import {ToolOptionsProvider} from '../../contexts/ToolOptionsContext'
+import {rootReducer} from '../../modules'
+import type {RootReducerState} from '../../modules/types'
+import type {MediaToolOptions} from '../../types'
+import {createTestRootState} from './rootState'
+import type {AssetSourceComponentProps} from 'sanity'
+
+type Opts = {
+  onSelect?: AssetSourceComponentProps['onSelect']
+  preloaded?: Partial<RootReducerState>
+  toolOptions?: Partial<MediaToolOptions>
+}
+
+export function renderWithProviders(ui: ReactElement, opts: Opts = {}) {
+  const {onSelect, preloaded, toolOptions} = opts
+
+  const store = configureStore({
+    reducer: rootReducer,
+    middleware: getDefaultMiddleware =>
+      getDefaultMiddleware({thunk: false, serializableCheck: false}),
+    preloadedState: createTestRootState(preloaded)
+  })
+
+  const options: MediaToolOptions = {
+    creditLine: {enabled: false},
+    directUploads: true,
+    ...toolOptions
+  }
+
+  const wrap = (node: ReactNode) => (
+    <Provider store={store}>
+      <ColorSchemeProvider scheme="light">
+        <ToolOptionsProvider options={options}>
+          <ThemeProvider theme={studioTheme}>
+            <ToastProvider>
+              <AssetBrowserDispatchProvider onSelect={onSelect}>
+                {node}
+              </AssetBrowserDispatchProvider>
+            </ToastProvider>
+          </ThemeProvider>
+        </ToolOptionsProvider>
+      </ColorSchemeProvider>
+    </Provider>
+  )
+
+  return {store, ...render(wrap(ui))}
+}

package/src/__tests__/fixtures/rootState.ts

@@ -0,0 +1,27 @@
+import type {RootReducerState} from '../../modules/types'
+import {initialState as assetsInitialState} from '../../modules/assets'
+
+export function createTestRootState(overrides: Partial<RootReducerState> = {}): RootReducerState {
+  const base: RootReducerState = {
+    assets: {
+      ...assetsInitialState,
+      assetTypes: ['file', 'image']
+    },
+    debug: {badConnection: false, enabled: false},
+    dialog: {items: []},
+    notifications: {items: []},
+    search: {facets: [], query: ''},
+    selected: {assets: [], document: undefined, documentAssetIds: []},
+    tags: {
+      allIds: [],
+      byIds: {},
+      creating: false,
+      fetchCount: -1,
+      fetching: false,
+      panelVisible: true
+    },
+    uploads: {allIds: [], byIds: {}}
+  }
+
+  return {...base, ...overrides} as RootReducerState
+}

package/src/__tests__/fixtures/withinDialog.ts

@@ -0,0 +1,28 @@
+import {within, type Screen} from '@testing-library/react'
+
+/** Topmost Sanity dialog matching `name` (handles animated duplicate layers). */
+export function getDialogRoot(name: RegExp, base: Screen): HTMLElement {
+  const dialogs = base.getAllByRole('dialog', {name})
+  const el = dialogs.at(-1)
+  if (!el) {
+    throw new Error(`No dialog found matching ${name}`)
+  }
+  return el
+}
+
+/** Scoped queries for that dialog. */
+export function withinDialog(name: RegExp, base: Screen) {
+  return within(getDialogRoot(name, base))
+}
+
+/**
+ * Sanity `TextInput` is not always exposed as a labellable control; use the native input by `name`.
+ */
+export function inputByName(dialogName: RegExp, base: Screen, name: string): HTMLInputElement {
+  const root = getDialogRoot(dialogName, base)
+  const input = root.querySelector(`input[name="${name}"]`)
+  if (!input || !(input instanceof HTMLInputElement)) {
+    throw new Error(`No input name="${name}" in dialog matching ${dialogName}`)
+  }
+  return input
+}

package/src/components/AutoTagInputWrapper/index.tsx

@@ -0,0 +1,82 @@
+import {useToast} from '@sanity/ui'
+import {useEffect, useRef} from 'react'
+import {type InputProps} from 'sanity'
+import {applyMediaTags} from '../../utils/applyMediaTags'
+import {useToolOptions} from '../../contexts/ToolOptionsContext'
+import useVersionedClient from '../../hooks/useVersionedClient'
+
+type AssetValue = {
+  _type: 'image' | 'file'
+  asset?: {
+    _ref: string
+    _type: 'reference'
+  }
+}
+
+export type AutoTagInputProps = InputProps & {
+  mediaTags?: string[]
+}
+
+/**
+ * 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 function AutoTagInput(props: AutoTagInputProps) {
+  const {renderDefault, schemaType, value, mediaTags: mediaTagsProp} = props
+  const toast = useToast()
+
+  // Prop takes precedence; fall back to schemaType.options.mediaTags (set for browser pre-filtering)
+  const mediaTags =
+    mediaTagsProp ?? (schemaType?.options as {mediaTags?: string[]} | undefined)?.mediaTags
+
+  const client = useVersionedClient()
+  const {createTagsOnUpload} = useToolOptions()
+
+  const prevAssetRef = useRef<string | undefined>(undefined)
+  const isInitialMount = useRef(true)
+
+  const currentAssetRef = (value as AssetValue | undefined)?.asset?._ref
+
+  useEffect(() => {
+    if (isInitialMount.current) {
+      isInitialMount.current = false
+      prevAssetRef.current = currentAssetRef
+      return
+    }
+
+    const previousRef = prevAssetRef.current
+    prevAssetRef.current = currentAssetRef
+
+    if (!mediaTags?.length || !currentAssetRef || currentAssetRef === previousRef) return
+
+    applyMediaTags({
+      client,
+      assetId: currentAssetRef,
+      mediaTags,
+      createTagsOnUpload
+    }).catch(err => {
+      console.error('[sanity-plugin-media] Failed to apply auto-tags:', err)
+      const label = mediaTags.length === 1 ? 'tag' : 'tags'
+      toast.push({closable: true, status: 'error', title: `Failed to apply the media ${label} ${mediaTags.join(', ')}`})
+    })
+  }, [currentAssetRef, mediaTags, client, createTagsOnUpload])
+
+  return renderDefault(props as InputProps)
+}
+
+export default AutoTagInput

package/src/components/Browser/Browser.test.tsx

@@ -0,0 +1,44 @@
+import {describe, expect, it, vi, beforeEach} from 'vitest'
+import {render, screen, waitFor} from '@testing-library/react'
+import {studioTheme, ThemeProvider, ToastProvider} from '@sanity/ui'
+import {ColorSchemeProvider} from 'sanity'
+import {of} from 'rxjs'
+import Browser from './index'
+import {createListenMock} from '../../__tests__/fixtures/listenMock'
+import {createMockSanityClient} from '../../__tests__/fixtures/mockSanityClient'
+import {ToolOptionsProvider} from '../../contexts/ToolOptionsContext'
+import useVersionedClient from '../../hooks/useVersionedClient'
+
+vi.mock('../../hooks/useVersionedClient', () => ({
+  default: vi.fn()
+}))
+
+describe('Browser', () => {
+  beforeEach(() => {
+    const fetch = vi.fn().mockReturnValue(of({items: []}))
+    vi.mocked(useVersionedClient).mockReturnValue(
+      createMockSanityClient({
+        listen: createListenMock(),
+        observable: {fetch}
+      })
+    )
+  })
+
+  it('renders Browse Assets header in tool mode', async () => {
+    render(
+      <ColorSchemeProvider scheme="light">
+        <ThemeProvider theme={studioTheme}>
+          <ToastProvider>
+            <ToolOptionsProvider options={{creditLine: {enabled: false}}}>
+              <Browser />
+            </ToolOptionsProvider>
+          </ToastProvider>
+        </ThemeProvider>
+      </ColorSchemeProvider>
+    )
+
+    await waitFor(() => {
+      expect(screen.getByText('Browse Assets')).toBeInTheDocument()
+    })
+  })
+})

package/src/components/Browser/index.tsx

@@ -1,15 +1,8 @@
-import type {MutationEvent} from '@sanity/client'
 import {Card, Flex, PortalProvider} from '@sanity/ui'
-import type {Asset, Tag} from '../../types'
-import groq from 'groq'
-import {useEffect, useState} from 'react'
-import {useDispatch} from 'react-redux'
+import {useState} from 'react'
 import {type AssetSourceComponentProps, type SanityDocument} from 'sanity'
-import {TAG_DOCUMENT_NAME} from '../../constants'
 import {AssetBrowserDispatchProvider} from '../../contexts/AssetSourceDispatchContext'
 import useVersionedClient from '../../hooks/useVersionedClient'
-import {assetsActions} from '../../modules/assets'
-import {tagsActions} from '../../modules/tags'
 import GlobalStyle from '../../styled/GlobalStyles'
 import Controls from '../Controls'
 import DebugControls from '../DebugControls'
@@ -21,6 +14,7 @@ import PickedBar from '../PickedBar'
 import ReduxProvider from '../ReduxProvider'
 import TagsPanel from '../TagsPanel'
 import UploadDropzone from '../UploadDropzone'
+import {useBrowserInit} from './useBrowserInit'
 
 type Props = {
   assetType?: AssetSourceComponentProps['assetType']
@@ -28,71 +22,20 @@ type Props = {
   onClose?: AssetSourceComponentProps['onClose']
   onSelect?: AssetSourceComponentProps['onSelect']
   selectedAssets?: AssetSourceComponentProps['selectedAssets']
+  schemaType?: AssetSourceComponentProps['schemaType']
 }
 
-const BrowserContent = ({onClose}: {onClose?: AssetSourceComponentProps['onClose']}) => {
+const BrowserContent = ({
+  onClose,
+  schemaType
+}: {
+  onClose?: AssetSourceComponentProps['onClose']
+  schemaType?: AssetSourceComponentProps['schemaType']
+}) => {
   const client = useVersionedClient()
   const [portalElement, setPortalElement] = useState<HTMLDivElement | null>(null)
-  const dispatch = useDispatch()
-
-  useEffect(() => {
-    const handleAssetUpdate = (update: MutationEvent) => {
-      const {documentId, result, transition} = update
-
-      if (transition === 'appear') {
-        dispatch(assetsActions.listenerCreateQueue({asset: result as Asset}))
-      }
-
-      if (transition === 'disappear') {
-        dispatch(assetsActions.listenerDeleteQueue({assetId: documentId}))
-      }
-
-      if (transition === 'update') {
-        dispatch(assetsActions.listenerUpdateQueue({asset: result as Asset}))
-      }
-    }
-
-    const handleTagUpdate = (update: MutationEvent) => {
-      const {documentId, result, transition} = update
-
-      if (transition === 'appear') {
-        dispatch(tagsActions.listenerCreateQueue({tag: result as Tag}))
-      }
-
-      if (transition === 'disappear') {
-        dispatch(tagsActions.listenerDeleteQueue({tagId: documentId}))
-      }
-
-      if (transition === 'update') {
-        dispatch(tagsActions.listenerUpdateQueue({tag: result as Tag}))
-      }
-    }
-
-    // Fetch assets: first page
-    dispatch(assetsActions.loadPageIndex({pageIndex: 0}))
-
-    // Fetch all tags
-    dispatch(tagsActions.fetchRequest())
-
-    // Listen for asset and tag changes in published documents.
-    // Remember that Sanity listeners ignore joins, order clauses and projections!
-    // Also note that changes to the selected document (if present) will automatically re-load the media plugin
-    // due to the desk pane re-rendering.
-    const subscriptionAsset = client
-      .listen(
-        groq`*[_type in ["sanity.fileAsset", "sanity.imageAsset"] && !(_id in path("drafts.**"))]`
-      )
-      .subscribe(handleAssetUpdate)
-
-    const subscriptionTag = client
-      .listen(groq`*[_type == "${TAG_DOCUMENT_NAME}" && !(_id in path("drafts.**"))]`)
-      .subscribe(handleTagUpdate)
 
-    return () => {
-      subscriptionAsset?.unsubscribe()
-      subscriptionTag?.unsubscribe()
-    }
-  }, [client, dispatch])
+  useBrowserInit(client, schemaType)
 
   return (
     <PortalProvider element={portalElement}>
@@ -137,7 +80,7 @@ const Browser = (props: Props) => {
     >
       <AssetBrowserDispatchProvider onSelect={props?.onSelect}>
         <GlobalStyle />
-        <BrowserContent onClose={props?.onClose} />
+        <BrowserContent onClose={props?.onClose} schemaType={props?.schemaType} />
       </AssetBrowserDispatchProvider>
     </ReduxProvider>
   )

package/src/components/Browser/useBrowserInit.ts

@@ -0,0 +1,126 @@
+import type {MutationEvent, SanityClient} from '@sanity/client'
+import groq from 'groq'
+import {useEffect} from 'react'
+import {useDispatch, useSelector} from 'react-redux'
+import type {AssetSourceComponentProps} from 'sanity'
+import type {Dispatch} from 'redux'
+
+import {inputs} from '../../config/searchFacets'
+import {TAG_DOCUMENT_NAME} from '../../constants'
+import {searchActions} from '../../modules/search'
+import {tagsActions} from '../../modules/tags'
+import type {RootReducerState} from '../../modules/types'
+import type {Asset, Tag} from '../../types'
+import {assetsActions} from '../../modules/assets'
+
+function getMediaTagNames(schemaType?: AssetSourceComponentProps['schemaType']): string[] {
+  const mediaTags = (schemaType?.options as {mediaTags?: string[]} | undefined)?.mediaTags
+  if (!mediaTags?.length) return []
+  const unique = new Set(
+    mediaTags.map(t => t?.trim()).filter((t): t is string => Boolean(t?.length))
+  )
+  return Array.from(unique)
+}
+
+function createAssetHandler(dispatch: Dispatch) {
+  return (update: MutationEvent) => {
+    const {documentId, result, transition} = update
+
+    switch (transition) {
+      case 'appear':
+        dispatch(assetsActions.listenerCreateQueue({asset: result as Asset}))
+        break
+      case 'disappear':
+        dispatch(assetsActions.listenerDeleteQueue({assetId: documentId}))
+        break
+      case 'update':
+        dispatch(assetsActions.listenerUpdateQueue({asset: result as Asset}))
+        break
+      default:
+        break
+    }
+  }
+}
+
+function createTagHandler(dispatch: Dispatch) {
+  return (update: MutationEvent) => {
+    const {documentId, result, transition} = update
+
+    switch (transition) {
+      case 'appear':
+        dispatch(tagsActions.listenerCreateQueue({tag: result as Tag}))
+        break
+      case 'disappear':
+        dispatch(tagsActions.listenerDeleteQueue({tagId: documentId}))
+        break
+      case 'update':
+        dispatch(tagsActions.listenerUpdateQueue({tag: result as Tag}))
+        break
+      default:
+        break
+    }
+  }
+}
+
+export function useBrowserInit(
+  client: SanityClient,
+  schemaType?: AssetSourceComponentProps['schemaType']
+): void {
+  const dispatch = useDispatch()
+  const tagsByIds = useSelector((state: RootReducerState) => state.tags.byIds)
+  const tagsFetchCount = useSelector((state: RootReducerState) => state.tags.fetchCount)
+
+  const tagNames = getMediaTagNames(schemaType)
+  const hasMediaTags = tagNames.length > 0
+
+  useEffect(() => {
+    if (!hasMediaTags) {
+      dispatch(searchActions.facetsClear())
+    }
+
+    dispatch(tagsActions.fetchRequest())
+
+    const assetSubscription = client
+      .listen(
+        groq`*[_type in ["sanity.fileAsset", "sanity.imageAsset"] && !(_id in path("drafts.**"))]`
+      )
+      .subscribe(createAssetHandler(dispatch))
+
+    const tagSubscription = client
+      .listen(groq`*[_type == "${TAG_DOCUMENT_NAME}" && !(_id in path("drafts.**"))]`)
+      .subscribe(createTagHandler(dispatch))
+
+    return () => {
+      assetSubscription.unsubscribe()
+      tagSubscription.unsubscribe()
+    }
+  }, [client, dispatch, hasMediaTags])
+
+  // When mediaTags are configured, wait for the tag fetch to complete then apply facets.
+  // Dispatching clear + add synchronously keeps all actions within assetsSearchEpic's
+  // 400ms debounce window, so the browser performs exactly one asset fetch on open.
+  useEffect(() => {
+    if (!hasMediaTags || tagsFetchCount < 0) return
+
+    const tagFacetInput = inputs.tag
+    if (tagFacetInput.type !== 'searchable') return
+
+    const resolvedTags = tagNames
+      .map(name => Object.values(tagsByIds).find(item => item.tag.name.current === name))
+      .filter((item): item is NonNullable<typeof item> => Boolean(item))
+
+    dispatch(searchActions.facetsClear())
+
+    for (const tagItem of resolvedTags) {
+      dispatch(
+        searchActions.facetsAdd({
+          facet: {
+            ...tagFacetInput,
+            operatorType: 'references',
+            value: {label: tagItem.tag.name.current, value: tagItem.tag._id}
+          }
+        })
+      )
+    }
+  }, [tagsFetchCount, hasMediaTags]) // eslint-disable-line react-hooks/exhaustive-deps
+}