@sanity/assist 4.2.0 → 4.3.0

package/dist/index.d.ts

@@ -1,4 +1,8 @@
+import {AgentActionPath} from '@sanity/client/stega'
 import {CurrentUser} from 'sanity'
+import {DocumentFieldActionDivider} from 'sanity'
+import {DocumentFieldActionGroup} from 'sanity'
+import {DocumentFieldActionItem} from 'sanity'
 import {JSX as JSX_2} from 'react/jsx-runtime'
 import {ObjectSchemaType} from 'sanity'
 import {Path} from 'sanity'
@@ -8,7 +12,15 @@ import {PortableTextMarkDefinition} from '@portabletext/types'
 import {PortableTextSpan} from '@portabletext/types'
 import {SanityClient} from 'sanity'
 import type {SanityClient as SanityClient_2} from '@sanity/client'
+import {SanityDocumentLike} from 'sanity'
 import {SchemaType} from 'sanity'
+import {SchemaType as SchemaType_2} from '@sanity/types'
+
+declare interface AgentActionConditionalPath {
+  path: AgentActionPath
+  readOnly: boolean
+  hidden: boolean
+}
 
 export declare const assist: Plugin_2<void | AssistPluginConfig>
 
@@ -62,6 +74,135 @@ export declare interface AssistConfig {
   temperature?: number
 }
 
+export declare type AssistFieldActionGroup = Omit<
+  DocumentFieldActionGroup,
+  'renderAsButton' | 'expanded' | 'children'
+> & {
+  children: AssistFieldActionNode[]
+}
+
+export declare type AssistFieldActionItem = Omit<
+  DocumentFieldActionItem,
+  'renderAsButton' | 'selected' | 'onAction'
+> & {
+  onAction: () => void | Promise<void>
+}
+
+export declare type AssistFieldActionNode =
+  | AssistFieldActionItem
+  | AssistFieldActionGroup
+  | DocumentFieldActionDivider
+
+export declare interface AssistFieldActionProps {
+  /**
+   * `actionType` will be `document` for action invoked from the top right document action menu, and
+   * `field` when invoked from a field action menu.
+   */
+  actionType: 'document' | 'field'
+  /**
+   * This is the id of the current document pane; it contains `drafts.`or `versions. prefix` ect depending on context.
+   * Use this for `documentId` when calling any `client.agent.action`.
+   *
+   * It is generally recommended to call actions from the studio like this:
+   * ```ts
+   * await client.agent.action.generate({
+   *   targetDocument: {
+   *      operation: 'createIfNotExists',
+   *      _id: props.documentIdForAction,
+   *      _type: props.documentSchemaType.name,
+   *      initialValues: props.getDocumentValue()
+   *   },
+   *   //...
+   * })
+   * ```
+   */
+  documentIdForAction: string
+  /**
+   * Schema type of the current document.
+   * @see documentIdForAction
+   */
+  documentSchemaType: ObjectSchemaType
+  /**
+   * Returns the current document value.
+   *
+   * Prefer passing this function to your hooks instead of passing the document value directly to avoid unnecessary re-renders.
+   * @see documentIdForAction
+   */
+  getDocumentValue: () => SanityDocumentLike
+  /**
+   * Returns the current readOnly and hidden state of all conditional members in the current document form.
+   *
+   * Intended to be passed to agent actions `conditionalPaths.paths`.
+   */
+  getConditionalPaths: () => AgentActionConditionalPath[]
+  /**
+   * `schemaId` for the current workspace.
+   *
+   * Note: the workspace schema has to be deployed using `sanity schema deploy` or `sanity deploy`.
+   *
+   * Use this for `schemaId` when calling any `client.agent.action`.
+   *
+   * It is generally recommended to call actions from the studio like this:
+   * ```ts
+   * await client.agent.action.generate({
+   *   targetDocument: {
+   *      operation: 'createIfNotExists',
+   *      _id: props.documentIdForAction,
+   *      _type: props.documentSchemaType.name,
+   *      initialValues: props.getDocumentValue()
+   *   },
+   *   //...
+   * })
+   */
+  schemaId: string
+  /**
+   * This is the schema type of the field the actions will be attached to (ie, schemaType for `path`)
+   *
+   * It can be used with agent actions using `target.path`, to scope the action to a specific field.
+   *
+   * It is generally recommended to call actions from the studio like this:
+   * ```ts
+   * await client.agent.action.generate({
+   *   targetDocument: {
+   *      operation: 'createIfNotExists',
+   *      _id: props.documentIdForAction,
+   *      _type: props.documentSchemaType.name,
+   *      initialValues: props.getDocumentValue()
+   *   },
+   *   target: {
+   *      path: props.path
+   *   },
+   * })
+   * ```
+   */
+  path: AgentActionPath
+  /**
+   * This is the schema type of the field the actions will be attached to (ie, schemaType for `path`).
+   *
+   * Typically useful to dynamically return different actions based on the schema type of the field.
+   *
+   * ```ts
+   * if(isObjectSchemaType(schemaType)) {
+   *   return [
+   *     defineAssistFieldAction({
+   *       title: 'Fill the object fields',
+   *       icon: RobotIcon,
+   *       onAction: () => {
+   *         //...
+   *       }
+   *     })
+   *   ]
+   * }
+   * return useMemo(() => {
+   *
+   *
+   * }, [])
+   *
+   * ```
+   */
+  schemaType: SchemaType_2
+}
+
 export declare interface AssistOptions {
   aiAssist?: {
     /** Set to true to disable assistance for this field or type */
@@ -80,6 +221,10 @@ declare interface AssistPluginConfig {
    * Config that affects all instructions
    */
   assist?: AssistConfig
+  fieldActions?: {
+    title?: string
+    useFieldActions?: (props: AssistFieldActionProps) => AssistFieldActionNode[]
+  }
   /**
    * @internal
    */
@@ -104,6 +249,35 @@ declare interface ContextBlock {
 
 export declare const contextDocumentTypeName: 'assist.instruction.context'
 
+/**
+ *
+ */
+export declare interface CustomInput {
+  /**
+   * Id for the input
+   */
+  id: string
+  /**
+   * Title of the input field
+   */
+  title: string
+  /**
+   * Additional info that will be displayed over the input
+   */
+  description?: string
+}
+
+export declare type CustomInputResult = {
+  /**
+   * Identifies which custom input the `result`belongs to
+   */
+  input: CustomInput
+  /**
+   * The text provided by the user in the input
+   */
+  result: string
+}
+
 /**
  * Default implementation for plugin config `translate.field.translationOutputs`
  *
@@ -111,6 +285,16 @@ export declare const contextDocumentTypeName: 'assist.instruction.context'
  */
 export declare const defaultLanguageOutputs: TranslationOutputsFunction
 
+export declare function defineAssistFieldAction(
+  action: Omit<AssistFieldActionItem, 'type'>,
+): AssistFieldActionItem
+
+export declare function defineAssistFieldActionGroup(
+  group: Omit<AssistFieldActionGroup, 'type'>,
+): AssistFieldActionGroup
+
+export declare function defineFieldActionDivider(): DocumentFieldActionDivider
+
 export declare interface DocumentMember {
   schemaType: SchemaType
   path: Path
@@ -252,6 +436,17 @@ export declare interface FieldTranslationConfig {
   maxPathDepth?: number
 }
 
+export declare type GetUserInput = (args: {
+  /**
+   * Dialog title
+   */
+  title: string
+  /**
+   * One titled input per array item
+   */
+  inputs: CustomInput[]
+}) => Promise<CustomInputResult[] | undefined>
+
 declare type InlinePromptBlock = PortableTextSpan | FieldRef | UserInputBlock | ContextBlock
 
 declare const instructionContextTypeName: 'sanity.assist.instruction.context'
@@ -395,6 +590,68 @@ declare interface UserInputBlock {
 
 declare const userInputTypeName: 'sanity.assist.instruction.userInput'
 
+/**
+ * `useUserInput` returns a function that can be used to await user input.
+ *
+ * Useful for custom `fieldActions` to get user input for populating Agent Action requests,.
+ *
+ * ```ts
+ *  fieldActions: {
+ *   useFieldActions: (props) => {
+ *     const {
+ *       documentSchemaType,
+ *       schemaId,
+ *       getDocumentValue,
+ *       getConditionalPaths,
+ *       documentIdForAction,
+ *     } = props
+ *     const client = useClient({apiVersion: 'vX'})
+ *     const getUserInput = useUserInput()
+ *     return useMemo(() => {
+ *       return [
+ *         defineAssistFieldAction({
+ *           title: 'Log user input',
+ *           icon: UserIcon,
+ *           onAction: async () => {
+ *             const input = await getUserInput({
+ *               title: 'Topic',
+ *               inputs: [{id: 'about', title: 'What should the article be about?'}],
+ *             })
+ *             if (!input) return // user canceled input
+ *             await client.agent.action.generate({
+ *               schemaId,
+ *               targetDocument: {
+ *                 operation: 'createIfNotExists',
+ *                 _id: documentIdForAction,
+ *                 _type: documentSchemaType.name,
+ *                 initialValues: getDocumentValue(),
+ *               },
+ *               instruction: `
+ *                   Create a document about the following topic:
+ *                   $about
+ *                   ---
+ *                `,
+ *               instructionParams: {about: input[0].result},
+ *               conditionalPaths: {paths: getConditionalPaths()},
+ *             })
+ *           },
+ *         }),
+ *       ]
+ *     }, [
+ *       client,
+ *       documentSchemaType,
+ *       schemaId,
+ *       getDocumentValue,
+ *       getConditionalPaths,
+ *       documentIdForAction,
+ *       getUserInput,
+ *     ])
+ *   },
+ * }
+ * ```
+ */
+export declare function useUserInput(): GetUserInput
+
 export {}
 
 declare module 'sanity' {