sanity-plugin-documents-pane 1.0.0-v3-studio.1

package/src/DocumentsPane.tsx

@@ -0,0 +1,60 @@
+import React from 'react'
+import {Stack} from '@sanity/ui'
+
+import Documents from './Documents'
+import Feedback from './Feedback'
+import Debug from './Debug'
+import {DocumentsPaneProps} from './types'
+import resolveParams from './resolveParams'
+import resolveInitialValueTemplates from './resolveInitialValueTemplates'
+
+export default function DocumentsPane(props: DocumentsPaneProps) {
+  const {document, options} = props
+  const {
+    query,
+    params,
+    useDraft = false,
+    debug = false,
+    initialValueTemplates: initialValueTemplatesResolver,
+  } = options
+
+  if (useDraft && typeof params === 'function') {
+    return (
+      <Stack padding={4} space={5}>
+        <Feedback>
+          <code>useDraft</code> should not be <code>true</code> when supplying a function for
+          <code>params</code>
+        </Feedback>
+        {debug && <Debug query={query} />}
+      </Stack>
+    )
+  }
+
+  const paramValues = resolveParams({document, params, useDraft})
+
+  const initialValueTemplates = resolveInitialValueTemplates({
+    resolver: initialValueTemplatesResolver,
+    document,
+  })
+
+  if (!paramValues) {
+    return (
+      <Stack padding={4} space={5}>
+        <Feedback>
+          Parameters for this query could not be resolved. This may mean the document does not yet
+          exist or is incomplete.
+        </Feedback>
+        {debug && <Debug query={query} />}
+      </Stack>
+    )
+  }
+
+  return (
+    <Documents
+      query={query}
+      params={paramValues}
+      debug={debug}
+      initialValueTemplates={initialValueTemplates}
+    />
+  )
+}

package/src/Feedback.tsx

@@ -0,0 +1,18 @@
+import React from 'react'
+import {Card, Text} from '@sanity/ui'
+import type {BadgeTone} from '@sanity/ui'
+
+type FeedbackProps = {
+  children?: React.ReactNode
+  tone?: BadgeTone
+}
+
+export default function Feedback(props: FeedbackProps) {
+  const {children, tone = `caution`} = props
+
+  return (
+    <Card padding={3} radius={2} shadow={1} tone={tone}>
+      <Text size={1}>{children}</Text>
+    </Card>
+  )
+}

package/src/NewDocument.tsx

@@ -0,0 +1,40 @@
+import {Button, Card, Flex} from '@sanity/ui'
+import React from 'react'
+import {DocumentsPaneInitialValueTemplate} from './types'
+import {ComposeIcon} from '@sanity/icons'
+import {usePaneRouter} from 'sanity/desk'
+import {uuid} from '@sanity/uuid'
+
+interface NewDocumentProps {
+  initialValueTemplates: DocumentsPaneInitialValueTemplate[]
+}
+
+export default function NewDocument(props: NewDocumentProps) {
+  const {initialValueTemplates = []} = props
+  const {ReferenceChildLink} = usePaneRouter()
+
+  if (!initialValueTemplates.length) return null
+
+  return (
+    <Card borderBottom={true} padding={2}>
+      <Flex justify="flex-end" gap={1}>
+        {initialValueTemplates.map((template) => {
+          if (!template.template) {
+            return null
+          }
+          return (
+            <ReferenceChildLink
+              documentId={uuid()}
+              documentType={template.schemaType}
+              template={{id: template.template, params: template.parameters}}
+              parentRefPath={[]}
+              key={`${template.schemaType}-${template.template}`}
+            >
+              <Button icon={<ComposeIcon />} text={template.title} mode="bleed" as="span" />
+            </ReferenceChildLink>
+          )
+        })}
+      </Flex>
+    </Card>
+  )
+}

package/src/hooks/useListeningQuery.ts

@@ -0,0 +1,66 @@
+import {useEffect, useState, useRef} from 'react'
+import {catchError, distinctUntilChanged} from 'rxjs/operators'
+import isEqual from 'react-fast-compare'
+import type {SanityDocument} from 'sanity'
+import {useDocumentStore} from 'sanity/_unstable'
+
+type Params = Record<string, string | number | boolean | string[]>
+
+interface ListenQueryOptions {
+  tag?: string
+  apiVersion?: string
+}
+
+type ReturnShape = {
+  loading: boolean
+  error: boolean
+  data: SanityDocument[] | null
+}
+
+type Observable = {
+  unsubscribe: () => void
+}
+
+const DEFAULT_PARAMS = {}
+const DEFAULT_OPTIONS = {apiVersion: `v2022-05-09`}
+
+export default function useListeningQuery(
+  query: string,
+  params: Params = DEFAULT_PARAMS,
+  options: ListenQueryOptions = DEFAULT_OPTIONS
+): ReturnShape {
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState(false)
+  const [data, setData] = useState<SanityDocument[] | null>(null)
+  const subscription = useRef<null | Observable>(null)
+  const documentStore = useDocumentStore()
+
+  useEffect(() => {
+    if (query) {
+      subscription.current = documentStore
+        .listenQuery(query, params, options)
+        .pipe(
+          distinctUntilChanged(isEqual),
+          catchError((err) => {
+            console.error(err)
+            setError(err)
+            setLoading(false)
+            setData(null)
+
+            return err
+          })
+        )
+        .subscribe((documents: SanityDocument[]) => {
+          setData((current) => (isEqual(current, documents) ? current : documents))
+          setLoading(false)
+          setError(false)
+        })
+    }
+
+    return () => {
+      return subscription.current ? subscription.current.unsubscribe() : undefined
+    }
+  }, [query, params, options])
+
+  return {loading, error, data}
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import DocumentsPane from './DocumentsPane'
+
+export default DocumentsPane

package/src/parts.d.ts

@@ -0,0 +1,2 @@
+// Tells Typescript to skip typechecking imported parts
+declare module "part:@sanity/*";

package/src/resolveInitialValueTemplates.ts

@@ -0,0 +1,20 @@
+import {
+  DocumentsPaneInitialValueTemplate,
+  DocumentsPaneInitialValueTemplateResolver,
+  DocumentVersionsCollection,
+} from './types'
+
+interface ResolveInitialValueTemplatesOptions {
+  resolver: DocumentsPaneInitialValueTemplateResolver | undefined
+  document: DocumentVersionsCollection
+}
+
+export default function resolveInitialValueTemplates(
+  options: ResolveInitialValueTemplatesOptions
+): DocumentsPaneInitialValueTemplate[] {
+  const {resolver, document} = options || {}
+
+  if (!resolver) return []
+
+  return resolver({document})
+}

package/src/resolveParams.ts

@@ -0,0 +1,44 @@
+import {DocumentsPaneQueryParams, DocumentVersionsCollection} from './types'
+import delve from 'dlv'
+
+interface ResolveParamsOptions {
+  params?: DocumentsPaneQueryParams
+  document: DocumentVersionsCollection
+  useDraft: boolean
+}
+
+type ResolveParamsReturn = undefined | {[key: string]: string}
+
+function defaultResolver(options: ResolveParamsOptions): {
+  [key: string]: string | undefined
+} {
+  const {params, document, useDraft} = options
+
+  // params is optional
+  if (!params) return {}
+
+  // legacy useDraft behaviour
+  const doc = useDraft ? document.displayed : document.published
+
+  return Object.keys(params).reduce(
+    (acc, key) => ({
+      ...acc,
+      [key]: delve(doc, params[key as keyof DocumentsPaneQueryParams]),
+    }),
+    {}
+  )
+}
+
+export default function resolveParams(options: ResolveParamsOptions): ResolveParamsReturn {
+  const {params, document} = options
+
+  const resolvedParams = typeof params == 'function' ? params({document}) : defaultResolver(options)
+
+  // if any of the parameters are undefined, the query will error
+  // so return undefined so the UI can show a more appropriate message
+  if (Object.values(resolvedParams).includes(undefined)) return undefined
+
+  // Typescript can't tell that we've guarded against any value being undefined,
+  // so forcing the type
+  return resolvedParams as {[key: string]: string}
+}

package/src/types.ts

@@ -0,0 +1,34 @@
+import {SanityDocument} from '@sanity/client'
+
+export interface DocumentVersionsCollection {
+  displayed: SanityDocument
+  published: SanityDocument
+  draft: SanityDocument
+  historical: SanityDocument
+}
+
+// eslint-disable-next-line prettier/prettier
+export type DocumentsPaneQueryParams = (params: {document: DocumentVersionsCollection}) => ({[key: string]: string}) | {[key: string]: string}
+
+export interface DocumentsPaneInitialValueTemplate {
+  schemaType: string
+  template?: string
+  parameters?: {[key: string]: any}
+  title: string
+}
+
+// eslint-disable-next-line prettier/prettier
+export type DocumentsPaneInitialValueTemplateResolver = (params: {document: DocumentVersionsCollection}) => DocumentsPaneInitialValueTemplate[]
+
+export type DocumentsPaneOptions = {
+  query: string
+  params?: DocumentsPaneQueryParams
+  debug?: boolean
+  useDraft?: boolean
+  initialValueTemplates?: DocumentsPaneInitialValueTemplateResolver
+}
+
+export type DocumentsPaneProps = {
+  document: DocumentVersionsCollection
+  options: DocumentsPaneOptions
+}

package/v2-incompatible.js

@@ -0,0 +1,10 @@
+const {showIncompatiblePluginDialog} = require('@sanity/incompatible-plugin')
+const {name, version} = require('./package.json')
+
+export default showIncompatiblePluginDialog({
+  name: name,
+  versions: {
+    v3: version,
+    v2: '^1.1.0',
+  },
+})