@sanity/assist 4.3.1 → 4.4.0

package/README.md

@@ -35,7 +35,7 @@
 - [Adding translation actions to fields](#adding-translation-actions-to-fields)
 - [Translation style guide](#translation-style-guide)
 - [Custom field actions](#custom-field-actions)
-  - [useFieldActions](#usefieldaction)
+  - [useExampleFieldActions](#usefieldaction)
   - [Define helpers](#define-helpers)
   - [useUserInput](#useuserinput)
 - [License](#license)
@@ -949,40 +949,59 @@ assist({
 <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:
+or other custom actions into the AI Assist document and field action menus, use `fieldActions` plugin config.
+
+Because of react hook linting, we recommend defining the `useExampleFieldActions` outside the 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
-          },
-        })], [])
-    }
-  }
+//sanity.config.ts
+import {defineConfig} from 'sanity'
+import {assist, type AssistFieldActionProps, defineAssistFieldAction} from '@sanity/assist'
+
+function useExampleFieldActions(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
+      },
+    })], [])
+}
+
+export default defineConfig({
+  //...
+  plugins: [
+    //...other plugins
+    assist({
+      fieldActions: {
+        title: 'Custom actions',
+        useExampleFieldActions
+      }
+    })
+  ]
 })
 ```
 
-### `useFieldActions`
+### `useExampleFieldActions`
 
-`useFieldActions` is called for the document itself and for all fields within it. It can call React hooks.
+`useExampleFieldActions` 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`.
+It is recommended to wrap the returned actions in `useMemo`. The returned array can contain `undefined` values. 
+These will be filtered out.
+
 
 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
 
+Below are some examples of agent action integration.
+For more, see [HOW-TO_USE](../studio/examples/agentActions/HOW-TO-USE.md)
+
 ##### Fix spelling
 
 The following example adds a "Fix spelling" action to all fields and the document itself.
@@ -991,49 +1010,44 @@ It will fix spelling mistakes for the field it is invoked for (and all child fie
 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,
-      ])
-    },
-  },
-})
+function useExampleFieldActions(props: AssistFieldActionProps) {
+  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)
@@ -1047,44 +1061,41 @@ The action will:
 - 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 []
-        }
+function useExampleFieldActions(props: AssistFieldActionProps) {
+  const {
+    documentSchemaType,
+    actionType,
+    schemaId,
+    getDocumentValue,
+    getConditionalPaths,
+    documentIdForAction,
+    path,
+    schemaType,
+  } = props
+
+  // hook usage has to happen outside onAction, so preassemble state in useExampleFieldActions 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: `
+    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)
@@ -1099,35 +1110,33 @@ The action will:
                         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(),
-                },
-              })
+            instructionParams: {
+              doc: {type: 'document'},
+              field: {type: 'field', path},
+              lang: {type: 'field', path: ['language']},
             },
-          }),
-        ]
-      }, [
-        client,
-        documentSchemaType,
-        schemaId,
-        getDocumentValue,
-        getConditionalPaths,
-        documentIdForAction,
-        actionType,
-        path,
-        schemaType,
-      ])
-    },
-  },
-})
+            target: {
+              path,
+            },
+            conditionalPaths: {
+              paths: getConditionalPaths(),
+            },
+          })
+        },
+      }),
+    ]
+  }, [
+    client,
+    documentSchemaType,
+    schemaId,
+    getDocumentValue,
+    getConditionalPaths,
+    documentIdForAction,
+    actionType,
+    path,
+    schemaType,
+  ])
+}
 ```
 
 ### Define helpers
@@ -1136,7 +1145,7 @@ The action will:
 
 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`
+`onAction` _cannot_ call hooks. If state from hook is needed, it should be pre-assembled by `useExampleFieldActions`
 
 ```ts
 defineAssistFieldAction({
@@ -1151,10 +1160,12 @@ defineAssistFieldAction({
 #### `defineAssistFieldActionGroup`
 
 Adds a group to hold one or more actions (or nested groups).
+`children` can contain `undefined` values. These will be filtered out.
+A group that has an empty `children` array (or only undefined values) will be filtered out.
 
-By default, any actions returned by `useFieldActions` will be grouped under `title`.
+By default, any actions returned by `useExampleFieldActions` will be grouped under `title`.
 ```ts
-useFieldActions: (props) => {
+function useExampleFieldActions(props: AssistFieldActionProps) {
   return [
     defineAssistFieldAction({/* ... */}), 
     defineAssistFieldActionGroup({
@@ -1167,15 +1178,14 @@ useFieldActions: (props) => {
 }
 ```
 
-#### Only groups in `useFieldActions`
-If `useFieldActions` _only_ returns groups, the default wrapper group will be omitted. This allows full control over each group title.
+#### Only groups in `useExampleFieldActions`
+If `useExampleFieldActions` _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) => {
+function useExampleFieldActions(props: AssistFieldActionProps) {
   return useMemo(() => [
     defineAssistFieldAction({/* ... */}),
     defineFieldActionDivider(),
@@ -1198,45 +1208,41 @@ When the user completes the dialog, the user inputted text will be available (or
 
 
 ```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],
-      )
-    },
-  },
-})
+
+function useExampleFieldActions(props: AssistFieldActionProps) {
+  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

package/dist/index.d.mts

@@ -78,7 +78,11 @@ export declare type AssistFieldActionGroup = Omit<
   DocumentFieldActionGroup,
   'renderAsButton' | 'expanded' | 'children'
 > & {
-  children: AssistFieldActionNode[]
+  /**
+   * `children` can include undefined entries in the action array. These will be filtered out.
+   * If the group has no defined children, the group will also be filtered out.
+   */
+  children: (AssistFieldActionNode | undefined)[]
 }
 
 export declare type AssistFieldActionItem = Omit<
@@ -153,6 +157,8 @@ export declare interface AssistFieldActionProps {
    *   },
    *   //...
    * })
+   *
+   * ```
    */
   schemaId: string
   /**
@@ -201,6 +207,15 @@ export declare interface AssistFieldActionProps {
    * ```
    */
   schemaType: SchemaType_2
+  /**
+   * Schema type of the parent field or array item holding this field.
+   *
+   * This can be undefined if the action was unable to resolve the parent type is excluded from AI Assist.
+   *
+   * @see schemaType
+   * @see documentSchemaType
+   */
+  parentSchemaType?: SchemaType_2
 }
 
 export declare interface AssistOptions {
@@ -223,7 +238,10 @@ declare interface AssistPluginConfig {
   assist?: AssistConfig
   fieldActions?: {
     title?: string
-    useFieldActions?: (props: AssistFieldActionProps) => AssistFieldActionNode[]
+    /**
+     * The returned array can include `undefined` entries in the action array. These will be filtered out.
+     */
+    useFieldActions?: (props: AssistFieldActionProps) => (AssistFieldActionNode | undefined)[]
   }
   /**
    * @internal
@@ -525,7 +543,7 @@ declare interface PresetInstruction {
   prompt?: PromptTextBlock[]
   title?: string
   /**
-   * String key from @sanity/icons IconMap
+   * String key from `@sanity/icons` IconMap
    */
   icon?: string
   /**

package/dist/index.d.ts

@@ -78,7 +78,11 @@ export declare type AssistFieldActionGroup = Omit<
   DocumentFieldActionGroup,
   'renderAsButton' | 'expanded' | 'children'
 > & {
-  children: AssistFieldActionNode[]
+  /**
+   * `children` can include undefined entries in the action array. These will be filtered out.
+   * If the group has no defined children, the group will also be filtered out.
+   */
+  children: (AssistFieldActionNode | undefined)[]
 }
 
 export declare type AssistFieldActionItem = Omit<
@@ -153,6 +157,8 @@ export declare interface AssistFieldActionProps {
    *   },
    *   //...
    * })
+   *
+   * ```
    */
   schemaId: string
   /**
@@ -201,6 +207,15 @@ export declare interface AssistFieldActionProps {
    * ```
    */
   schemaType: SchemaType_2
+  /**
+   * Schema type of the parent field or array item holding this field.
+   *
+   * This can be undefined if the action was unable to resolve the parent type is excluded from AI Assist.
+   *
+   * @see schemaType
+   * @see documentSchemaType
+   */
+  parentSchemaType?: SchemaType_2
 }
 
 export declare interface AssistOptions {
@@ -223,7 +238,10 @@ declare interface AssistPluginConfig {
   assist?: AssistConfig
   fieldActions?: {
     title?: string
-    useFieldActions?: (props: AssistFieldActionProps) => AssistFieldActionNode[]
+    /**
+     * The returned array can include `undefined` entries in the action array. These will be filtered out.
+     */
+    useFieldActions?: (props: AssistFieldActionProps) => (AssistFieldActionNode | undefined)[]
   }
   /**
    * @internal
@@ -525,7 +543,7 @@ declare interface PresetInstruction {
   prompt?: PromptTextBlock[]
   title?: string
   /**
-   * String key from @sanity/icons IconMap
+   * String key from `@sanity/icons` IconMap
    */
   icon?: string
   /**

package/dist/index.esm.js

@@ -211,6 +211,9 @@ function getPathKey(path) {
 function getInstructionTitle(instruction2) {
   return instruction2?.title ?? "Untitled";
 }
+function isDefined(t) {
+  return t != null;
+}
 function isPortableTextArray(type) {
   return type.of.find((t) => isType(t, "block"));
 }
@@ -397,6 +400,12 @@ function getTypeIcon(schemaType) {
   }
   return isType(schemaType, "slug") ? LinkIcon : isType(schemaType, "image") ? ImageIcon : schemaType.jsonType === "array" && isPortableTextArray(schemaType) ? BlockContentIcon : schemaType.jsonType === "array" ? OlistIcon : schemaType.jsonType === "object" ? BlockquoteIcon : schemaType.jsonType === "string" ? StringIcon : DocumentIcon;
 }
+function asFieldRefsByTypePath(fieldRefs) {
+  return fieldRefs.reduce(
+    (acc, ref) => ({ ...acc, [ref.key]: ref }),
+    {}
+  );
+}
 function getFieldRefsWithDocument(schemaType) {
   const fields = getFieldRefs(schemaType);
   return [
@@ -1026,7 +1035,7 @@ function useAssistDocumentContextValue(documentId, documentType) {
   } = useDocumentPane(), { draft, published, version } = editState || {}, assistableDocumentId = selectedReleaseId ? getVersionId(documentId, selectedReleaseId) : documentSchemaType.liveEdit ? documentId : getDraftId(documentId), documentIsNew = selectedReleaseId ? !version?._id : !draft?._id && !published?._id, documentIsAssistable = selectedReleaseId ? !!version : isDocAssistable(documentSchemaType, published, draft), { params } = useAiPaneRouter(), selectedPath = params[fieldPathParam], assistDocument = useStudioAssistDocument({
     documentId: assistableDocumentId,
     schemaType: documentSchemaType
-  }), { syntheticTasks, addSyntheticTask, removeSyntheticTask } = useSyntheticTasks(assistableDocumentId);
+  }), { syntheticTasks, addSyntheticTask, removeSyntheticTask } = useSyntheticTasks(assistableDocumentId), fieldRefs = getFieldRefs(documentSchemaType), fieldRefsByTypePath = asFieldRefsByTypePath(fieldRefs);
   return useMemo(() => {
     const base = {
       assistableDocumentId,
@@ -1040,7 +1049,9 @@ function useAssistDocumentContextValue(documentId, documentType) {
       selectedPath,
       syntheticTasks,
       addSyntheticTask,
-      removeSyntheticTask
+      removeSyntheticTask,
+      fieldRefs,
+      fieldRefsByTypePath
     };
     return assistDocument ? {
       ...base,
@@ -2870,12 +2881,12 @@ function useCustomFieldActions(props) {
     path: props.path
   });
   return useMemo(() => {
-    const title = fieldActions?.title, customActions = configActions?.map((node) => createSafeNode({
+    const title = fieldActions?.title, customActions = configActions?.filter(isDefined).map((node) => createSafeNode({
       node,
       pushToast,
       addSyntheticTask,
       removeSyntheticTask
-    })), onlyGroups = customActions?.length && customActions?.every((node) => node.type === "group");
+    })).filter(isDefined), onlyGroups = customActions?.length && customActions?.every((node) => node.type === "group");
     return (customActions?.length ? onlyGroups ? customActions : [
       {
         type: "group",
@@ -2892,12 +2903,13 @@ function createSafeNode(args) {
     case "action":
       return createSafeAction({ ...args, action: node });
     case "group":
-      return {
+      const children = node.children?.filter(isDefined).map((child) => createSafeNode({ ...args, node: child })).filter(isDefined);
+      return children?.length ? {
         ...node,
         renderAsButton: !1,
         expanded: !0,
-        children: node.children?.map((child) => createSafeNode({ ...args, node: child }))
-      };
+        children
+      } : void 0;
     case "divider":
     default:
       return node;
@@ -2955,7 +2967,8 @@ const assistFieldActions = {
       documentOnChange,
       documentSchemaType,
       selectedPath,
-      assistableDocumentId
+      assistableDocumentId,
+      fieldRefsByTypePath
     } = useAssistDocumentContext(), { value: docValue, formState } = useDocumentPane(), docValueRef = useRef(docValue), formStateRef = useRef(formState);
     formStateRef.current = formState;
     const currentUser = useCurrentUser(), isHidden = !assistDocument, pathKey = usePathKey(props.path), typePath = useTypePath(docValue, pathKey), assistDocumentId2 = assistDocument?._id, { requestRunInstruction } = useRequestRunInstruction({
@@ -3043,14 +3056,22 @@ const assistFieldActions = {
           path
         };
       }
-    ), []), customActions = useCustomFieldActions({
+    ), []), parentSchemaType = useMemo(() => {
+      if (props.path.length) {
+        if (props.path.length === 1)
+          return documentSchemaType;
+      } else return;
+      const parentPath = props.path.slice(0, -1), typePath2 = getTypePath(docValueRef.current, pathToString(parentPath));
+      return typePath2 ? fieldRefsByTypePath[typePath2]?.schemaType : void 0;
+    }, [fieldRefsByTypePath, props.path, documentSchemaType]), customActions = useCustomFieldActions({
       actionType: props.path.length ? "field" : "document",
       documentIdForAction: assistableDocumentId,
       schemaType,
       documentSchemaType,
       path: props.path,
       getDocumentValue,
-      getConditionalPaths
+      getConditionalPaths,
+      parentSchemaType
     }), manageInstructionsItem = useMemo(
       () => ({
         type: "action",