@sanity/assist 1.2.16 → 2.0.1

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
+}

package/src/types.ts

@@ -1,4 +1,4 @@
-import {SanityDocument, ValidationMarker} from 'sanity'
+import {SanityDocument} from 'sanity'
 import {PortableTextBlock, PortableTextMarkDefinition, PortableTextSpan} from '@portabletext/types'
 
 //id prefixes
@@ -26,6 +26,9 @@ export const fieldPresenceTypeName = 'sanity.assist.instructionTask.presence' as
 export const assistSerializedTypeName = 'sanity.assist.serialized.type' as const
 export const assistSerializedFieldTypeName = 'sanity.assist.serialized.field' as const
 
+export const outputFieldTypeName = 'sanity.assist.output.field' as const
+export const outputTypeTypeName = 'sanity.assist.output.type' as const
+
 //url params
 export const inspectParam = 'inspect' as const
 export const fieldPathParam = 'pathKey' as const
@@ -34,27 +37,29 @@ export const instructionParam = 'instruction' as const
 // other constants
 export const documentRootKey = '<document>'
 
-export interface SerializedSchemaMember {
+export type SerializedSchemaMember = Omit<SerializedSchemaType, 'name' | '_type'> & {
   _type?: typeof assistSerializedFieldTypeName
-  type: string
-  name: string
-  title?: string
-  values?: string[]
-  of?: SerializedSchemaMember[]
-  to?: {type: string}[]
+  name?: string
 }
 
 export interface SerializedSchemaType {
   _type?: typeof assistSerializedTypeName
   _id?: string
   type: string
+  name: string
   title?: string
-  name?: string
   fields?: SerializedSchemaMember[]
-  of?: {type: string}[]
-  to?: {type: string}[]
+  of?: SerializedSchemaMember[]
+  to?: SerializedSchemaMember[]
+  annotations?: SerializedSchemaMember[]
+  inlineOf?: SerializedSchemaMember[]
+  values?: string[] | {value: string; title?: string}[]
+  hidden?: boolean | 'function'
+  readOnly?: boolean | 'function'
   options?: {
+    /** equivalent to options.aiAssist.imageDescriptionField - not renamed in the api for backwards compatability */
     imagePromptField?: string
+    embeddingsIndex?: string
   }
 }
 
@@ -63,14 +68,42 @@ export interface AssistDocument extends SanityDocument {
   instructions?: StudioInstruction[]
 }
 
-export interface StudioAssistDocument {
+export interface PresetInstruction {
+  _key: string
+  prompt?: PromptTextBlock[]
+
+  title?: string
+  /**
+   * String key from @sanity/icons IconMap
+   */
+  icon?: string
+
+  /**
+   * Type/field filter
+   */
+  output?: (OutputFieldItem | OutputTypeItem)[]
+}
+
+export interface PresetField {
+  path?: string
+  instructions?: PresetInstruction[]
+}
+
+export interface AssistPreset {
+  fields?: PresetField[]
+}
+
+export interface SanityAssistDocument {
   _id: string
   _type: typeof assistDocumentTypeName
   fields?: StudioAssistField[]
+}
 
-  // added
+export interface StudioAssistDocument extends SanityAssistDocument {
+  // added after loading
   tasks?: InstructionTask[]
 }
+
 export interface AssistField {
   _key: string
   _type: typeof assistFieldTypeName
@@ -108,7 +141,10 @@ export interface UserInputBlock {
 }
 
 export type InlinePromptBlock = PortableTextSpan | FieldRef | UserInputBlock | ContextBlock
-export type PromptTextBlock = PortableTextBlock<never, InlinePromptBlock, 'normal', never>
+export type PromptTextBlock = Omit<
+  PortableTextBlock<never, InlinePromptBlock, 'normal', never>,
+  '_type'
+> & {_type: 'block'}
 
 export type PromptBlock = PromptTextBlock | FieldRef | ContextBlock | UserInputBlock
 
@@ -149,10 +185,10 @@ export interface StudioInstruction {
   userId?: string
   title?: string
   placeholder?: string
+  output?: (OutputFieldItem | OutputTypeItem)[]
 
   //added after query / synthetic fields
   tasks?: InstructionTask[]
-  validation?: ValidationMarker[]
 }
 
 export interface AssistTasksStatus {
@@ -166,3 +202,19 @@ export interface AssistInspectorRouteParams {
   [fieldPathParam]?: string
   [instructionParam]?: string
 }
+
+export interface OutputFieldItem {
+  _type: typeof outputFieldTypeName
+  _key: string
+  //path relative to the field the instruction is for (same as _key)
+  relativePath?: string
+}
+
+export interface OutputTypeItem {
+  _type: typeof outputTypeTypeName
+  _key: string
+  /* array item type name */
+  type?: string
+  //path relative to the array-field the instruction is for, can be empty string (the array itself, same as _key)
+  relativePath?: string
+}