@sanity/assist 1.2.16 → 2.0.0

package/dist/index.cjs.mjs

@@ -3,4 +3,5 @@ import cjs from './index.js';
 export const SchemaTypeTool = cjs.SchemaTypeTool;
 export const assist = cjs.assist;
 export const contextDocumentTypeName = cjs.contextDocumentTypeName;
+export const defaultLanguageOutputs = cjs.defaultLanguageOutputs;
 

package/dist/index.d.ts

@@ -1,31 +1,197 @@
 import {JSX as JSX_2} from 'react/jsx-runtime'
+import {Path} from 'sanity'
 import {Plugin as Plugin_2} from 'sanity'
-import {SanityClient} from '@sanity/client'
+import {SanityClient} from 'sanity'
+import {SanityClient as SanityClient_2} from '@sanity/client'
+import {SchemaType} from 'sanity'
 
 export declare const assist: Plugin_2<void | AssistPluginConfig>
 
 export declare interface AssistOptions {
-  aiWritingAssistance?: {
+  aiAssist?: {
     /** Set to true to disable assistance for this field or type */
     exclude?: boolean
+    /**
+     * Set to true to add translation field-action to the field.
+     * Only has an effect in document types configured for document or field level translations.
+     */
+    translateAction?: boolean
   }
 }
 
 declare interface AssistPluginConfig {
-  /**
-   * Set this to false to disable model migration from the alpha version of this plugin
-   */
-  alphaMigration?: boolean
+  translate?: TranslationConfig
   /**
    * @internal
    */
-  __customApiClient?: (defaultClient: SanityClient) => SanityClient
+  __customApiClient?: (defaultClient: SanityClient_2) => SanityClient_2
 }
 
 export declare const contextDocumentTypeName: 'assist.instruction.context'
 
+/**
+ * Default implementation for plugin config `translate.field.translationOutputs`
+ *
+ * @see FieldTranslationConfig#translationOutputs
+ */
+export declare const defaultLanguageOutputs: TranslationOutputsFunction
+
+export declare interface DocumentMember {
+  schemaType: SchemaType
+  path: Path
+  name: string
+  value: unknown
+}
+
+export declare 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 declare 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 declare interface Language {
+  id: string
+  title?: string
+}
+
+export declare type LanguageCallback = (
+  client: SanityClient,
+  selectedLanguageParams: Record<string, unknown>,
+) => Promise<Language[]>
+
 export declare function SchemaTypeTool(): JSX_2.Element
 
+export declare 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
+}
+
+export declare interface TranslationOutput {
+  /** Language id */
+  id: string
+  outputPath: Path
+}
+
+export declare type TranslationOutputsFunction = (
+  documentMember: DocumentMember,
+  enclosingType: SchemaType,
+  translateFromLanguageId: string,
+  translateToLanguageIds: string[],
+) => TranslationOutput[] | undefined
+
 export {}
 
 declare module 'sanity' {
@@ -38,13 +204,89 @@ declare module 'sanity' {
   interface DocumentOptions extends AssistOptions {}
   interface FileOptions extends AssistOptions {}
   interface GeopointOptions extends AssistOptions {}
-  interface ImageOptions extends AssistOptions {
-    imagePromptField?: string
-    captionField?: string
+  interface ImageOptions {
+    aiAssist?: AssistOptions['aiAssist'] & {
+      /**
+       * When set, an image will be created whenever the `imageInstructionField` is written to by
+       * an AI Assist instruction.
+       *
+       * The value output by AI Assist will be use as an image prompt for an generative image AI.
+       *
+       * This means that instructions directly for the field or instructions that visit the field when running,
+       * will result in the image being changed.
+       *
+       * `imageInstructionField` must be a child-path relative to the image field, ie:
+       * * field
+       * * path.to.field
+       *
+       * ### Example
+       * ```ts
+       * defineType({
+       *   type: 'image',
+       *   name: 'articleImage',
+       *   fields: [
+       *     defineField({
+       *       type: 'text',
+       *       name: 'imagePrompt',
+       *       title: 'Image prompt',
+       *       rows: 2,
+       *     }),
+       *   ],
+       *   options: {
+       *      aiAssist: {
+       *        imageInstructionField: 'imagePrompt',
+       *     }
+       *   },
+       * })
+       * ```
+       */
+      imageInstructionField?: string
+      /**
+       * When set, an image description will be automatically created for the image.
+       *
+       * `imageDescriptionField` must be a child-path relative to the image field, ie:
+       * * field
+       * * path.to.field
+       *
+       * Whenever the image asset for the field is changed in the Studio,
+       * an image description is generated and set into the `imageDescriptionField`.
+       *
+       * ### Example
+       * ```ts
+       * defineType({
+       *   type: 'image',
+       *   name: 'articleImage',
+       *   fields: [
+       *     defineField({
+       *       type: 'string',
+       *       name: 'altText',
+       *       title: 'Alt text',
+       *     }),
+       *   ],
+       *   options: {
+       *      aiAssist: {
+       *        imageDescriptionField: 'altText',
+       *     }
+       *   },
+       * })
+       * ```
+       */
+      imageDescriptionField?: string
+    }
   }
   interface NumberOptions extends AssistOptions {}
   interface ObjectOptions extends AssistOptions {}
-  interface ReferenceBaseOptions extends AssistOptions {}
+  interface ReferenceBaseOptions {
+    aiAssist?: {
+      /** Set to true to disable assistance for this field or type */
+      exclude?: boolean
+      /**
+       * When set, the reference field will allow instructions to be added to it.
+       * Should be the name of the embeddings-index where assist will look for contextually relevant documents
+       * */
+      embeddingsIndex?: string
+    }
+  }
   interface SlugOptions extends AssistOptions {}
   interface StringOptions extends AssistOptions {}
   interface TextOptions extends AssistOptions {}