feat(sanity): add perspectiveOverride option

packages/sanity/src/core/releases/hooks/usePerspective.tsx

@@ -42,21 +42,33 @@ export interface PerspectiveValue {
   globalReleaseDocumentId: string
 }
 
+/**
+ * @internal
+ */
+export interface PerspectiveOptions {
+  /**
+   * The perspective is normally determined by the router. The `perspectiveOverride` prop can be
+   * used to explicitly set the perspective, overriding the perspective provided by the router.
+   */
+  perspectiveOverride?: string
+}
+
 const EMPTY_ARRAY: string[] = []
 /**
  * TODO: Improve distinction between global and pane perspectives.
  *
  * @internal
  */
-export function usePerspective(): PerspectiveValue {
+export function usePerspective({perspectiveOverride}: PerspectiveOptions = {}): PerspectiveValue {
   const router = useRouter()
   const {data: releases, archivedReleases} = useReleases()
   // TODO: Actually validate the perspective value, if it's not a valid perspective, we should fallback to undefined
-  const currentPerspectiveName = router.stickyParams.perspective as
+  const currentPerspectiveName = (perspectiveOverride ?? router.stickyParams.perspective) as
     | 'published'
     | `r${string}`
     | undefined
 
+  // TODO: When `perspectiveOverride` is set, exclusion should not have an effect.
   const excludedPerspectives = useMemo(
     () => router.stickyParams.excludedPerspectives?.split(',') || EMPTY_ARRAY,
     [router.stickyParams.excludedPerspectives],

packages/sanity/src/structure/panes/document/DocumentPaneProvider.tsx

@@ -74,7 +74,7 @@ import {usePreviewUrl} from './usePreviewUrl'
  */
 // eslint-disable-next-line complexity, max-statements
 export const DocumentPaneProvider = memo((props: DocumentPaneProviderProps) => {
-  const {children, index, pane, paneKey, onFocusPath} = props
+  const {children, index, pane, paneKey, onFocusPath, perspectiveOverride} = props
   const schema = useSchema()
   const templates = useTemplates()
   const {setDocumentMeta} = useCopyPaste()
@@ -104,7 +104,9 @@ export const DocumentPaneProvider = memo((props: DocumentPaneProviderProps) => {
   const documentId = getPublishedId(documentIdRaw)
   const documentType = options.type
   const params = useUnique(paneRouter.params) || EMPTY_PARAMS
-  const {selectedPerspectiveName, selectedReleaseId, selectedPerspective} = usePerspective()
+  const {selectedPerspectiveName, selectedReleaseId, selectedPerspective} = usePerspective({
+    perspectiveOverride,
+  })
 
   /* Version and the global perspective should match.
    * If user clicks on add document, and then switches to another version, he should click again on create document.

packages/sanity/src/structure/panes/document/types.ts

@@ -9,4 +9,9 @@ export type TimelineMode = 'since' | 'rev' | 'closed'
 export type DocumentPaneProviderProps = {
   children?: React.ReactNode
   onFocusPath?: (path: Path) => void
+  /**
+   * The perspective is normally determined by the router. The `perspectiveOverride` prop can be
+   * used to explicitly set the perspective, overriding the perspective provided by the router.
+   */
+  perspectiveOverride?: string
 } & BaseStructureToolPaneProps<'document'>