@sanity/assist 4.2.0 → 4.3.1

package/README.md

@@ -34,6 +34,10 @@
   - [Configure](#configure-field-translations)
 - [Adding translation actions to fields](#adding-translation-actions-to-fields)
 - [Translation style guide](#translation-style-guide)
+- [Custom field actions](#custom-field-actions)
+  - [useFieldActions](#usefieldaction)
+  - [Define helpers](#define-helpers)
+  - [useUserInput](#useuserinput)
 - [License](#license)
 - [Develop \& test](#develop--test)
   - [Release new version](#release-new-version)
@@ -940,6 +944,301 @@ assist({
 })
 ```
 
+## Custom field actions
+
+<img width="513" alt="Field action menu with custom actions" src="https://github.com/user-attachments/assets/c613f692-4983-4acc-a8c2-8fb60294682a" />
+
+To incorporate [Agent Actions](https://www.sanity.io/docs/agent-actions?utm_source=github.com&utm_medium=organic_social&utm_campaign=ai-assist&utm_content=)
+or other custom actions into the AI Assist document and field action menus, use `fieldActions` plugin config:
+
+```ts
+assist({
+  fieldActions: {
+    title: 'Custom actions',
+    useFieldActions: (props: AssistFieldActionProps) => {
+      return useMemo(() => [
+        defineAssistFieldAction({
+          title: 'Do something',
+          icon: ActionIcon,
+          onAction: async () => {
+            // perform an (async) action
+            // errors will be caught and displayed in a toast
+            // until the action completes or fails, AI Assist "presence" will show up on the top of the document
+          },
+        })], [])
+    }
+  }
+})
+```
+
+### `useFieldActions`
+
+`useFieldActions` is called for the document itself and for all fields within it. It can call React hooks.
+Actions returned by the hook will be added to the corresponding document or field menu.
+
+It is recommended to wrap the returned actions in `useMemo`.
+
+See TSDocs for [AssistFieldActionProps](./src/fieldActions/customFieldActions.tsx) for details on how each
+prop can be used to parameterize Agent Actions on sanity client.
+
+#### Agent Action examples
+
+##### Fix spelling
+
+The following example adds a "Fix spelling" action to all fields and the document itself.
+
+It will fix spelling mistakes for the field it is invoked for (and all child fields, for arrays and objects),
+by calling `client.agent.action.transform`.
+
+```ts
+ assist({
+  fieldActions: {
+    title: 'Custom actions',
+    useFieldActions: (props) => {
+      const {
+        documentSchemaType,
+        schemaId,
+        getDocumentValue,
+        getConditionalPaths,
+        documentIdForAction,
+        path,
+      } = props
+      const client = useClient({apiVersion: 'vX'})
+      return useMemo(() => {
+        return [
+          defineAssistFieldAction({
+            title: 'Fix spelling',
+            icon: TranslateIcon,
+            onAction: async () => {
+              await client.agent.action.transform({
+                schemaId,
+                documentId: documentIdForAction,
+                instruction: 'Fix any spelling mistakes',
+                instructionParams: {field: {type: 'field', path}},
+                // no need to send path for document actions
+                target: path.length ? {path} : undefined,
+                conditionalPaths: {paths: getConditionalPaths()},
+              })
+            },
+          }),
+        ]
+      }, [
+        client,
+        documentSchemaType,
+        schemaId,
+        getDocumentValue,
+        getConditionalPaths,
+        documentIdForAction,
+        path,
+      ])
+    },
+  },
+})
+```
+
+##### Fill field (contextually aware)
+
+The following example adds a "Fill field" action to all fields in the document by calling `client.agent.action.generate`.
+
+The action will:
+- create the document as a draft if it does not exist, respecting initial values (`targetDocument`)
+- use existing document state to determine what should be put in the the field (`instruction`, `instructionParams`)
+- pass the current readOnly and hidden state currently use by the document form to the Agent Action, so it respects it (`conditionalPaths`)
+- output to the field the action started from (`target.path`)
+
+```ts
+ assist({
+  fieldActions: {
+    title: 'Custom actions',
+    useFieldActions: (props) => {
+      const {
+        documentSchemaType,
+        actionType,
+        schemaId,
+        getDocumentValue,
+        getConditionalPaths,
+        documentIdForAction,
+        path,
+        schemaType,
+      } = props
+
+      // hook usage has to happen outside onAction, so preassemble state in useFieldActions and pass to useMemo
+      const client = useClient({apiVersion: 'vX'})
+
+      return useMemo(() => {
+        if (actionType === 'document') {
+          // in this case we dont want a document action
+          return []
+        }
+
+        return [
+          defineAssistFieldAction({
+            title: 'Fill field',
+            icon: EditIcon,
+            onAction: async () => {
+              await client.agent.action.generate({
+                schemaId,
+                targetDocument: {
+                  operation: 'createIfNotExists',
+                  _id: documentIdForAction,
+                  _type: documentSchemaType.name,
+                  initialValues: getDocumentValue(),
+                },
+                instruction: `
+                        We are generating a new value for a document field.
+                        The document type is ${documentSchemaType.name}, and the document type title is ${documentSchemaType.title}
+                        The document language is: "$lang" (use en-US if unspecified)
+                        The document value is:
+                        $doc
+                        ---
+                        We are in the following field:
+                        JSON-path: ${pathToString(path)}
+                        Title: ${schemaType.title}
+                        Value: $field (consider it empty if undefined)
+                        ---
+                        Generate a new field value. The new value should be relevant to the document type and context.
+                        Keep it interesting. Generate using the document language.
+                     `,
+                instructionParams: {
+                  doc: {type: 'document'},
+                  field: {type: 'field', path},
+                  lang: {type: 'field', path: ['language']},
+                },
+                target: {
+                  path,
+                },
+                conditionalPaths: {
+                  paths: getConditionalPaths(),
+                },
+              })
+            },
+          }),
+        ]
+      }, [
+        client,
+        documentSchemaType,
+        schemaId,
+        getDocumentValue,
+        getConditionalPaths,
+        documentIdForAction,
+        actionType,
+        path,
+        schemaType,
+      ])
+    },
+  },
+})
+```
+
+### Define helpers
+
+#### `defineAssistFieldAction`
+
+Adds a single action that will appear in the document/field action menu.
+
+`onAction` _cannot_ call hooks. If state from hook is needed, it should be pre-assembled by `useFieldActions`
+
+```ts
+defineAssistFieldAction({
+  title: 'Do something',
+  icon: ActionIcon,
+  onAction: async () => {
+    //perform actions
+  },
+})
+```
+
+#### `defineAssistFieldActionGroup`
+
+Adds a group to hold one or more actions (or nested groups).
+
+By default, any actions returned by `useFieldActions` will be grouped under `title`.
+```ts
+useFieldActions: (props) => {
+  return [
+    defineAssistFieldAction({/* ... */}), 
+    defineAssistFieldActionGroup({
+      title: 'More actions',
+      children: [
+        defineAssistFieldAction({/* ... */}),
+      ],
+    })
+  ]
+}
+```
+
+#### Only groups in `useFieldActions`
+If `useFieldActions` _only_ returns groups, the default wrapper group will be omitted. This allows full control over each group title.
+
+#### `defineFieldActionDivider`
+Adds a divider between actions or groups. Takes no arguments:
+
+```ts
+
+useFieldActions: (props) => {
+  return useMemo(() => [
+    defineAssistFieldAction({/* ... */}),
+    defineFieldActionDivider(),
+    defineAssistFieldAction({/* ... */}),
+  ], [])
+}
+```
+
+### `useUserInput`
+
+<img width="522" alt="user input dialog" src="https://github.com/user-attachments/assets/86966468-9a28-4c0b-99f3-e4b80fdbe691" />
+
+For certain actions, it is useful to have the user provide additional information or details that can be used
+as parameters for the action.
+
+`useUserInput` returns a `getUserInput` function that can be called and awaited to return input from the user.
+
+The `getUserInput` function takes input configuration and will display an input dialog to the user.
+When the user completes the dialog, the user inputted text will be available (or undefined if the user closed the dialog).
+
+
+```ts
+({
+  fieldActions: {
+    title: 'Custom actions',
+    useFieldActions: (props) => {
+      const getUserInput = useUserInput()
+
+      return useMemo(
+        () => [
+          defineAssistFieldAction({
+            title: 'Do something with user input',
+            onAction: async () => {
+              const inputResult = await getUserInput({
+                title: 'What do you want to do?', // dialog title
+                inputs: [
+                  {
+                    id: 'topic',
+                    title: 'Topic',
+                  },
+                  {
+                    id: 'facts',
+                    title: 'Facts',
+                    description: 'Provide additional facts that will be used by the action',
+                  },
+                ],
+              })
+              if (!inputResult) {
+                return // user closed the dialog
+              }
+
+              //use the result from each input
+              //const [{result: topic}, {result: facts}] = inputResult
+            },
+          }),
+        ],
+        [getUserInput],
+      )
+    },
+  },
+})
+```
+
 ## Caveats
 
 Large Language Models (LLMs) are a new technology. Constraints and limitations are still being explored,

package/dist/index.d.mts

@@ -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,10 +436,29 @@ 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'
 
+/**
+ * Returns true if the `schemaType` or any of its parent types (`schemaType.type`)` has `name` equal
+ * to `typeName`.
+ *
+ * Useful for checking if `schemaType` is a type alias of `ìmage`, `code` or similar.
+ */
+export declare function isType(schemaType: SchemaType, typeName: string): boolean
+
 export declare interface Language {
   id: string
   title?: string
@@ -395,6 +598,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' {