@sanity/assist 1.2.15 → 2.0.0

package/src/translate/paths.test.ts

@@ -0,0 +1,133 @@
+import {describe, expect, test} from 'vitest'
+import {Schema} from '@sanity/schema'
+import {defineType, ObjectSchemaType, pathToString, SanityDocumentLike, typed} from 'sanity'
+import {
+  defaultLanguageOutputs,
+  FieldLanguageMap,
+  getDocumentMembersFlat,
+  getFieldLanguageMap,
+} from './paths'
+
+describe('paths', () => {
+  test('should return internationalizedArrayString paths and find translation mappings', () => {
+    const docSchema: ObjectSchemaType = Schema.compile({
+      name: 'test',
+      types: [
+        defineType({
+          type: 'document',
+          name: 'article',
+          fields: [
+            {type: 'string', name: 'title'},
+            {
+              type: 'object',
+              name: 'localeTitle',
+              fields: [
+                {type: 'string', name: 'en'},
+                {type: 'string', name: 'no'},
+              ],
+            },
+            {
+              type: 'array',
+              name: 'translations',
+              of: [
+                {
+                  type: 'object',
+                  name: 'internationalizedArrayString',
+                  fields: [{type: 'string', name: 'value'}],
+                },
+              ],
+            },
+          ],
+        }),
+      ],
+    }).get('article')
+
+    const doc: SanityDocumentLike = {
+      _id: 'na',
+      _type: 'article',
+      title: 'some title',
+      localeTitle: {
+        en: 'en string',
+      },
+      translations: [
+        {
+          _type: 'internationalizedArrayString',
+          _key: 'en',
+          value: 'some string',
+        },
+      ],
+    }
+
+    const members = getDocumentMembersFlat(doc, docSchema)
+    expect(members.map((p) => pathToString(p.path))).toEqual([
+      'title',
+      'localeTitle',
+      'localeTitle.en',
+      // this path has no value in the document, so are not included
+      //'localeTitle.no',
+      'translations',
+      'translations[_key=="en"]',
+      'translations[_key=="en"].value',
+      // these path has no value in the document, so are not included
+      //'translations[_key=="nb"]',
+      //'translations[_key=="nb"].value',
+    ])
+
+    const transMap = getFieldLanguageMap(docSchema, members, 'en', ['nb'], defaultLanguageOutputs)
+
+    expect(transMap).toEqual(
+      typed<FieldLanguageMap[]>([
+        {
+          inputLanguageId: 'en',
+          inputPath: ['translations', {_key: 'en'}],
+          outputs: [{id: 'nb', outputPath: ['translations', {_key: 'nb'}]}],
+        },
+      ])
+    )
+  })
+
+  test('should use first type in array when array item is missing _type', () => {
+    const docSchema: ObjectSchemaType = Schema.compile({
+      name: 'test',
+      types: [
+        defineType({
+          type: 'document',
+          name: 'article',
+          fields: [
+            {
+              type: 'array',
+              name: 'translations',
+              of: [
+                {
+                  type: 'object',
+                  name: 'internationalizedArrayString',
+                  fields: [{type: 'string', name: 'value'}],
+                },
+              ],
+            },
+          ],
+        }),
+      ],
+    }).get('article')
+
+    const doc: SanityDocumentLike = {
+      _id: 'na',
+      _type: 'article',
+      translations: [
+        {
+          //assume type is missing in the data for some reason
+          //_type: 'internationalizedArrayString',
+          _key: 'en',
+          value: 'some string',
+        },
+      ],
+    }
+
+    const members = getDocumentMembersFlat(doc, docSchema)
+    expect(members.map((p) => pathToString(p.path))).toEqual([
+      'translations',
+      'translations[_key=="en"]',
+      'translations[_key=="en"].value',
+    ])
+  })
+})

package/src/translate/paths.ts

@@ -0,0 +1,175 @@
+import {
+  isDocumentSchemaType,
+  isKeySegment,
+  ObjectSchemaType,
+  Path,
+  pathToString,
+  SanityDocumentLike,
+} from 'sanity'
+import {extractWithPath} from '@sanity/mutator'
+import {DocumentMember, TranslationOutput, TranslationOutputsFunction} from './types'
+
+export interface FieldLanguageMap {
+  inputLanguageId: string
+  inputPath: Path
+  outputs: TranslationOutput[]
+}
+
+const MAX_DEPTH = 6
+
+export function getDocumentMembersFlat(doc: SanityDocumentLike, schemaType: ObjectSchemaType) {
+  if (!isDocumentSchemaType(schemaType)) {
+    console.error(`Schema type is not a document`)
+    return []
+  }
+
+  return extractPaths(doc, schemaType, [], MAX_DEPTH)
+}
+
+function extractPaths(
+  doc: SanityDocumentLike,
+  schemaType: ObjectSchemaType,
+  path: Path,
+  maxDepth: number
+): DocumentMember[] {
+  if (path.length >= maxDepth) {
+    return []
+  }
+
+  return schemaType.fields.reduce<DocumentMember[]>((acc, field) => {
+    const fieldPath = [...path, field.name]
+    const fieldSchema = field.type
+    const {value} = extractWithPath(pathToString(fieldPath), doc)[0] ?? {}
+    if (!value) {
+      return acc
+    }
+
+    const thisFieldWithPath: DocumentMember = {
+      path: fieldPath,
+      name: field.name,
+      schemaType: fieldSchema,
+      value,
+    }
+
+    if (fieldSchema.jsonType === 'object') {
+      const innerFields = extractPaths(doc, fieldSchema, fieldPath, maxDepth)
+
+      return [...acc, thisFieldWithPath, ...innerFields]
+    } else if (
+      fieldSchema.jsonType === 'array' &&
+      fieldSchema.of.length &&
+      fieldSchema.of.some((item) => 'fields' in item)
+    ) {
+      const {value: arrayValue} = extractWithPath(pathToString(fieldPath), doc)[0] ?? {}
+
+      let arrayPaths: DocumentMember[] = []
+      if ((arrayValue as any)?.length) {
+        for (const item of arrayValue as any[]) {
+          const itemPath = [...fieldPath, {_key: item._key}]
+          let itemSchema = fieldSchema.of.find((t) => t.name === item._type)
+          if (!item._type) {
+            itemSchema = fieldSchema.of[0]
+            console.warn(
+              'Array item is missing _type - using the first defined type in the array.of schema',
+              {
+                itemPath,
+                item,
+                itemSchema,
+              }
+            )
+          }
+          if (item._key && itemSchema) {
+            const innerFields = extractPaths(
+              doc,
+              itemSchema as ObjectSchemaType,
+              itemPath,
+              maxDepth
+            )
+            const arrayMember = {
+              path: itemPath,
+              name: item._key,
+              schemaType: itemSchema,
+              value: item,
+            }
+            arrayPaths = [...arrayPaths, arrayMember, ...innerFields]
+          }
+        }
+      }
+
+      return [...acc, thisFieldWithPath, ...arrayPaths]
+    }
+
+    return [...acc, thisFieldWithPath]
+  }, [])
+}
+
+/**
+ * Default implementation for plugin config `translate.field.translationOutputs`
+ *
+ * @see FieldTranslationConfig#translationOutputs
+ */
+export const defaultLanguageOutputs: TranslationOutputsFunction = function (
+  member,
+  enclosingType,
+  translateFromLanguageId,
+  translateToLanguageIds
+) {
+  if (
+    member.schemaType.jsonType === 'object' &&
+    member.schemaType.name.startsWith('internationalizedArray')
+  ) {
+    const pathEnd = member.path.slice(-1)
+
+    const language = isKeySegment(pathEnd[0]) ? pathEnd[0]._key : null
+    return language === translateFromLanguageId
+      ? translateToLanguageIds.map((translateToId) => ({
+          id: translateToId,
+          outputPath: [...member.path.slice(0, -1), {_key: translateToId}],
+        }))
+      : undefined
+  }
+
+  if (enclosingType.jsonType === 'object' && enclosingType.name.startsWith('locale')) {
+    return translateFromLanguageId === member.name
+      ? translateToLanguageIds.map((translateToId) => ({
+          id: translateToId,
+          outputPath: [...member.path.slice(0, -1), translateToId],
+        }))
+      : undefined
+  }
+
+  return undefined
+}
+
+export function getFieldLanguageMap(
+  documentSchema: ObjectSchemaType,
+  documentMembers: DocumentMember[],
+  translateFromLanguageId: string,
+  outputLanguageIds: string[],
+  langFn: TranslationOutputsFunction
+): FieldLanguageMap[] {
+  const translationMaps: FieldLanguageMap[] = []
+  for (const member of documentMembers) {
+    const parentPath = member.path.slice(0, -1)
+    const enclosingType =
+      documentMembers.find((m) => pathToString(m.path) === pathToString(parentPath))?.schemaType ??
+      documentSchema
+
+    const translations = langFn(
+      member,
+      enclosingType,
+      translateFromLanguageId,
+      outputLanguageIds
+    )?.filter((translation) => translation.id !== translateFromLanguageId)
+
+    if (translations) {
+      translationMaps.push({
+        inputLanguageId: translateFromLanguageId,
+        inputPath: member.path,
+        outputs: translations,
+      })
+    }
+  }
+
+  return translationMaps
+}

package/src/translate/translateActions.tsx

@@ -0,0 +1,188 @@
+/* eslint-disable react-hooks/rules-of-hooks */
+import {
+  DocumentFieldAction,
+  DocumentFieldActionGroup,
+  DocumentFieldActionItem,
+  DocumentFieldActionProps,
+  ObjectSchemaType,
+} from 'sanity'
+import {TranslateIcon} from '@sanity/icons'
+import {useMemo, useRef} from 'react'
+import {useApiClient, useTranslate} from '../useApiClient'
+import {useAiAssistanceConfig} from '../assistLayout/AiAssistanceConfigContext'
+import {Box, Spinner} from '@sanity/ui'
+import {isAssistSupported} from '../helpers/assistSupported'
+import {useDocumentPane} from 'sanity/desk'
+import {useFieldTranslation} from './FieldTranslationProvider'
+import {useDraftDelayedTask} from '../assistDocument/RequestRunInstructionProvider'
+import {AssistOptions} from '../schemas/typeDefExtensions'
+import {getConditionalMembers} from '../helpers/conditionalMembers'
+
+function node(node: DocumentFieldActionItem | DocumentFieldActionGroup) {
+  return node
+}
+
+export type TranslateProps = DocumentFieldActionProps & {
+  documentIsAssistable?: boolean
+  documentSchemaType?: ObjectSchemaType
+}
+export const translateActions: DocumentFieldAction = {
+  name: 'sanity-assist-translate',
+  useAction(props: TranslateProps) {
+    const {config, status} = useAiAssistanceConfig()
+    const apiClient = useApiClient(config?.__customApiClient)
+
+    const {
+      schemaType: fieldSchemaType,
+      path,
+      documentId,
+      documentSchemaType,
+      documentIsAssistable,
+    } = props
+    const isDocumentLevel = path.length === 0
+    const readOnly = fieldSchemaType.readOnly === true
+
+    const docTransTypes = config.translate?.document?.documentTypes
+    const options = fieldSchemaType?.options as AssistOptions | undefined
+    const addFieldAction = isDocumentLevel || options?.aiAssist?.translateAction
+
+    //All props used here MUST have the same value always, or we break the rules of hooks (conditional hook usage)
+    const fieldTransEnabled =
+      addFieldAction &&
+      documentSchemaType &&
+      config.translate?.field?.documentTypes?.includes(documentSchemaType.name)
+    const documentTranslationEnabled =
+      addFieldAction &&
+      documentSchemaType &&
+      ((!docTransTypes && isAssistSupported(fieldSchemaType)) ||
+        docTransTypes?.includes(documentSchemaType.name))
+
+    // these checks are stable (ie, does not change after mount), so not breaking rules of hooks
+    if (documentSchemaType && (documentTranslationEnabled || fieldTransEnabled)) {
+      const {value: documentValue, onChange: documentOnChange, formState} = useDocumentPane()
+      const docRef = useRef(documentValue)
+      docRef.current = documentValue
+      const formStateRef = useRef(formState)
+      formStateRef.current = formState
+
+      const translationApi = useTranslate(apiClient)
+      const translate = useDraftDelayedTask({
+        documentOnChange,
+        isDocAssistable: documentIsAssistable ?? false,
+        task: translationApi.translate,
+      })
+
+      const languagePath = config.translate?.document?.languageField
+
+      // if this is true, it is stable, and not breaking rules of hooks
+      const translateDocumentAction = useMemo(() => {
+        if (!languagePath || !documentTranslationEnabled) {
+          return undefined
+        }
+        const title = path.length ? `Translate` : `Translate document`
+        return node({
+          type: 'action',
+          icon: translationApi.loading
+            ? () => (
+                <Box style={{height: 17}}>
+                  <Spinner style={{transform: 'translateY(6px)'}} />
+                </Box>
+              )
+            : TranslateIcon,
+          title,
+          onAction: () => {
+            if (translationApi.loading || !languagePath || !documentId) {
+              return
+            }
+            translate({
+              languagePath,
+              translatePath: path,
+              documentId: documentId ?? '',
+              conditionalMembers: formStateRef.current
+                ? getConditionalMembers(formStateRef.current)
+                : [],
+            })
+          },
+          renderAsButton: true,
+          disabled: translationApi.loading || readOnly,
+        })
+      }, [
+        languagePath,
+        translate,
+        documentId,
+        translationApi.loading,
+        documentTranslationEnabled,
+        path,
+        readOnly,
+      ])
+      const fieldTranslate = useFieldTranslation()
+      const openFieldTranslation = useDraftDelayedTask({
+        documentOnChange,
+        isDocAssistable: documentIsAssistable ?? false,
+        task: fieldTranslate.openFieldTranslation,
+      })
+
+      const translateFieldsAction = useMemo(
+        () =>
+          fieldTransEnabled
+            ? node({
+                type: 'action',
+                icon: fieldTranslate.translationLoading
+                  ? () => (
+                      <Box style={{height: 17}}>
+                        <Spinner style={{transform: 'translateY(6px)'}} />
+                      </Box>
+                    )
+                  : TranslateIcon,
+                title: `Translate fields...`,
+                onAction: () => {
+                  if (fieldTranslate.translationLoading || !documentId) {
+                    return
+                  }
+                  if (formStateRef.current) {
+                    getConditionalMembers(formStateRef.current)
+                  }
+                  openFieldTranslation({
+                    document: docRef.current,
+                    documentSchema: documentSchemaType,
+                    translatePath: path,
+                    conditionalMembers: formStateRef.current
+                      ? getConditionalMembers(formStateRef.current)
+                      : [],
+                  })
+                },
+                renderAsButton: true,
+                disabled: fieldTranslate.translationLoading || readOnly,
+              })
+            : undefined,
+        [
+          openFieldTranslation,
+          documentSchemaType,
+          documentId,
+          fieldTranslate.translationLoading,
+          fieldTransEnabled,
+          path,
+          readOnly,
+        ]
+      )
+
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      return useMemo(() => {
+        if (!status?.initialized) {
+          return undefined as unknown as DocumentFieldActionItem
+        }
+        return node({
+          type: 'group',
+          icon: () => null,
+          title: 'Translation',
+          children: [translateDocumentAction, translateFieldsAction].filter(
+            (c): c is DocumentFieldActionItem => !!c
+          ),
+          expanded: true,
+        })
+      }, [translateDocumentAction, translateFieldsAction, status])
+    }
+    // works but not supported by types
+    return undefined as unknown as DocumentFieldActionItem
+  },
+}

package/src/translate/types.ts

@@ -0,0 +1,160 @@
+import {Path, SanityClient, SchemaType} from 'sanity'
+
+export interface Language {
+  id: string
+  title?: string
+}
+
+export interface DocumentMember {
+  schemaType: SchemaType
+  path: Path
+  name: string
+  value: unknown
+}
+
+export interface TranslationOutput {
+  /** Language id */
+  id: string
+  outputPath: Path
+}
+
+export type TranslationOutputsFunction = (
+  documentMember: DocumentMember,
+  enclosingType: SchemaType,
+  translateFromLanguageId: string,
+  translateToLanguageIds: string[]
+) => TranslationOutput[] | undefined
+
+export type LanguageCallback = (
+  client: SanityClient,
+  selectedLanguageParams: Record<string, unknown>
+) => Promise<Language[]>
+
+export interface FieldTranslationConfig {
+  /**
+   * `documentTypes` should be an array of strings where each entry must match a name from your document schemas.
+   *
+   * If defined, matching document will get a "Translate fields" instruction added.
+   **/
+  documentTypes?: string[]
+
+  /**
+   *
+   * Used for display strings in the Studio, and to determine languages for field level translations
+   *
+   * If the studio is using the sanity-plugin-internationalized-array plugin, this
+   * should be set to the same configuration.
+   */
+  languages: Language[] | LanguageCallback
+
+  /**
+   * API version for client passed to LanguageCallback for languages
+   * https://www.sanity.io/docs/api-versioning
+   * @defaultValue '2022-11-27'
+   */
+  apiVersion?: string
+
+  /**
+   * Specify fields that should be available in the languages callback:
+   * ```tsx
+   * {
+   *   select: {
+   *     markets: 'markets'
+   *   },
+   *   languages: (client, {markets}) =>
+   *     client.fetch('*[_type == "language" && market in $markets]{id,title}', {markets})
+   * }
+   * ```
+   *
+   * If the studio is using the sanity-plugin-internationalized-array plugin, this
+   * should be set to the same configuration.
+   */
+  selectLanguageParams?: Record<string, string>
+
+  /**
+   * `translationOutputs` is used when the "Translate fields" instruction is started by a Studio user.
+   *
+   *  It determines the relationships between document paths: Given a document path and a language, into which
+   *  sibling paths should translations be output.
+
+   *
+   * `translationOutputs` is invoked once per path in the document (limited to a depth of 6), with the following:
+   *
+   *  * `documentMember` - the field or array item for a given path; contains the path and its schemaType,
+   *  * `enclosingType` - the schema type of parent holding the member
+   *  * `translateFromLanguageId` - the languageId for the language the user want to translate from
+   *  * `translateToLanguageIds` - all languageIds the user can translate to
+   *
+   * The function should return a `TranslationOutput[]` array that contains all the paths where translations from
+   * documentMember language (translateFromLanguageId) should be output.
+   *
+   * The function should return `undefined` for all documentMembers that should not be directly translated,
+   * or are nested fields under a translated path.
+   *
+   * ## Default function
+   *
+   * The default function for `translationOutputs` is configured to be automatically compatible with sanity-plugin-internationalized-array
+   * and object types prefixed with "locale".
+   *
+   * See <link to source for defaultTranslationOutputs> implementation details.
+   *
+   * ## Example
+   * A document has the following document members:
+   * * `{path: 'localeObject.en', schemaType: ObjectSchemaType}`
+   * * `{path: 'localeObject.en.title', schemaType: StringSchemaType}`
+   * * `{path: 'localeObject.de', schemaType: ObjectSchemaType}`,
+   * * `{path: 'localeObject.de.title', schemaType: StringSchemaType}`
+   *
+   * `translationOutputs` for invoked with `translateFromLanguageId` `en`,
+   * should only return [{id: 'de', outputPath: 'localeObject.de'}] for the `'localeObject.en'` path,
+   * and undefined for all the other members.
+   *
+   * ### Example implementation
+   * ```ts
+   * function translationOutputs(member, enclosingType, translateFromLanguageId, translateToLanguageIds)
+   *   if (enclosingType.jsonType === 'object' && enclosingType.name.startsWith('locale') && translateFromLanguageId === member.name) {
+   *      return translateToLanguageIds.map((translateToId) => ({
+   *         id: translateToId,
+   *         outputPath: [...member.path.slice(0, -1), translateToId],
+   *      }))
+   *   }
+   *   return undefined
+   * }
+   * ```
+   **/
+  translationOutputs?: TranslationOutputsFunction
+}
+
+export interface DocumentTranslationConfig {
+  /**
+   * Path to language field in documents. Can be a hidden field.
+   * For instance: 'config.language'
+   *
+   * For projects that use the `@sanity/document-internationalization` plugin,
+   * this should be the same as `languageField` config for that plugin.
+   *
+   * Default: 'language'
+   */
+  languageField: string
+
+  /**
+   * `documentTypes` should be an array of strings where each entry must match a name from your document schemas.
+   *
+   * If defined, this property will add a translate instruction to these document types.
+   * If undefined, the instruction will be added to all documents with aiAssistance enabled and a field matching `documentLanguageField` config.
+   *
+   * Documents with translation support will get a "Translate document>" instruction added.
+   **/
+  documentTypes?: string[]
+}
+
+export interface TranslationConfig {
+  /**
+   * Config for document types with fields in multiple languages in the same document.
+   */
+  field?: FieldTranslationConfig
+  /**
+   * Config for document types with a single language field that determines the language for the whole document.
+   */
+  document?: DocumentTranslationConfig
+}