@sanity/assist 2.0.5 → 3.0.1

package/dist/index.d.mts

@@ -0,0 +1,377 @@
+import {JSX as JSX_2} from 'react/jsx-runtime'
+import {Path} from 'sanity'
+import {Plugin as Plugin_2} from 'sanity'
+import {PortableTextBlock} from '@portabletext/types'
+import {PortableTextMarkDefinition} from '@portabletext/types'
+import {PortableTextSpan} from '@portabletext/types'
+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 {
+  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 {
+  translate?: TranslationConfig
+  /**
+   * @internal
+   */
+  __customApiClient?: (defaultClient: SanityClient_2) => SanityClient_2
+  /**
+   * @internal
+   */
+  __presets?: Record<string, AssistPreset>
+}
+
+declare interface AssistPreset {
+  fields?: PresetField[]
+}
+
+declare interface ContextBlock {
+  _type: typeof instructionContextTypeName
+  reference?: {
+    _type: 'reference'
+    _ref?: string
+  }
+}
+
+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[]
+}
+
+declare interface FieldRef extends PortableTextMarkDefinition {
+  _type: typeof fieldReferenceTypeName
+  path?: string
+}
+
+declare const fieldReferenceTypeName: 'sanity.assist.instruction.fieldRef'
+
+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
+}
+
+declare type InlinePromptBlock = PortableTextSpan | FieldRef | UserInputBlock | ContextBlock
+
+declare const instructionContextTypeName: 'sanity.assist.instruction.context'
+
+export declare interface Language {
+  id: string
+  title?: string
+}
+
+export declare type LanguageCallback = (
+  client: SanityClient,
+  selectedLanguageParams: Record<string, unknown>,
+) => Promise<Language[]>
+
+declare interface OutputFieldItem {
+  _type: typeof outputFieldTypeName
+  _key: string
+  relativePath?: string
+}
+
+declare const outputFieldTypeName: 'sanity.assist.output.field'
+
+declare interface OutputTypeItem {
+  _type: typeof outputTypeTypeName
+  _key: string
+  type?: string
+  relativePath?: string
+}
+
+declare const outputTypeTypeName: 'sanity.assist.output.type'
+
+declare interface PresetField {
+  path?: string
+  instructions?: PresetInstruction[]
+}
+
+declare interface PresetInstruction {
+  _key: string
+  prompt?: PromptTextBlock[]
+  title?: string
+  /**
+   * String key from @sanity/icons IconMap
+   */
+  icon?: string
+  /**
+   * Type/field filter
+   */
+  output?: (OutputFieldItem | OutputTypeItem)[]
+}
+
+declare type PromptTextBlock = Omit<
+  PortableTextBlock<never, InlinePromptBlock, 'normal', never>,
+  '_type'
+> & {
+  _type: 'block'
+}
+
+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
+
+declare interface UserInputBlock {
+  _type: typeof userInputTypeName
+  _key: string
+  message?: string
+  description?: string
+}
+
+declare const userInputTypeName: 'sanity.assist.instruction.userInput'
+
+export {}
+
+declare module 'sanity' {
+  interface ArrayOptions extends AssistOptions {}
+  interface BlockOptions extends AssistOptions {}
+  interface BooleanOptions extends AssistOptions {}
+  interface CrossDatasetReferenceOptions extends AssistOptions {}
+  interface DateOptions extends AssistOptions {}
+  interface DatetimeOptions extends AssistOptions {}
+  interface DocumentOptions extends AssistOptions {}
+  interface FileOptions extends AssistOptions {}
+  interface GeopointOptions extends AssistOptions {}
+  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 {
+    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 {}
+  interface UrlOptions extends AssistOptions {}
+  interface EmailOptions extends AssistOptions {}
+}