@sanity/assist 4.2.0 → 4.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/assist",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "You create the instructions; Sanity AI Assist does the rest.",
   "keywords": [
     "sanity",
@@ -51,7 +51,7 @@
   "dependencies": {
     "@sanity/icons": "^3.5.2",
     "@sanity/incompatible-plugin": "^1.0.4",
-    "@sanity/ui": "^2.10.9",
+    "@sanity/ui": "^2.15.18",
     "date-fns": "^3.6.0",
     "lodash": "^4.17.21",
     "lodash-es": "^4.17.21",
@@ -63,9 +63,9 @@
     "@commitlint/cli": "^19.2.1",
     "@commitlint/config-conventional": "^19.1.0",
     "@rollup/plugin-image": "^3.0.3",
-    "@sanity/pkg-utils": "^6.1.0",
+    "@sanity/pkg-utils": "^6.13.4",
     "@sanity/plugin-kit": "^3.1.10",
-    "@sanity/schema": "^3.81.0",
+    "@sanity/schema": "^3.91.0",
     "@sanity/semantic-release-preset": "^4.1.7",
     "@types/lodash": "^4.17.0",
     "@types/lodash-es": "^4.17.12",
@@ -83,11 +83,11 @@
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "rimraf": "^5.0.5",
-    "sanity": "^3.81.0",
+    "sanity": "^3.91.0",
     "semantic-release": "^23.0.8",
     "styled-components": "^6.1.16",
     "typescript": "^5.7.2",
-    "vitest": "^1.4.0"
+    "vitest": "^3.1.4"
   },
   "peerDependencies": {
     "@sanity/mutator": "^3.36.4",
@@ -96,9 +96,10 @@
     "styled-components": "^6.1"
   },
   "engines": {
-    "node": ">=14"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "browserslist": "extends @sanity/browserslist-config"
 }

package/src/assistDocument/AssistDocumentContext.tsx

@@ -1,7 +1,7 @@
 import {createContext, useContext} from 'react'
 import {DocumentInspector, ObjectSchemaType, PatchEvent} from 'sanity'
 
-import {StudioAssistDocument} from '../types'
+import {InstructionTask, StudioAssistDocument} from '../types'
 
 export type AssistDocumentContextValue = (
   | {assistDocument: StudioAssistDocument; loading: false}
@@ -19,6 +19,19 @@ export type AssistDocumentContextValue = (
   inspector: DocumentInspector | null
   selectedPath?: string
   documentOnChange: (event: PatchEvent) => void
+
+  /**
+   * Synthetic task is used to display AI presence at the document level for the user who started the action.
+   * These are not persisted, so other users will not see them.
+   * It is mostly a helper to give _some_ visual feedback to the user while a custom action is running.
+   * This also means that reloading the page will remove the icon.
+   *
+   * Agent Actions add their own "real" tasks, so if a custom action calls an Agent action, _those_ tasks
+   * are visible across sessions.
+   */
+  syntheticTasks?: InstructionTask[]
+  addSyntheticTask: (syntheticTask: InstructionTask) => void
+  removeSyntheticTask: (syntheticTask: InstructionTask) => void
 }
 
 export const AssistDocumentContext = createContext<AssistDocumentContextValue | undefined>(

package/src/assistDocument/hooks/useAssistDocumentContextValue.tsx

@@ -1,9 +1,9 @@
-import {useMemo} from 'react'
+import {useCallback, useEffect, useMemo, useState} from 'react'
 import {getDraftId, getVersionId, type ObjectSchemaType, useSchema} from 'sanity'
 import {useDocumentPane} from 'sanity/structure'
 
 import {useAiPaneRouter} from '../../assistInspector/helpers'
-import {fieldPathParam} from '../../types'
+import {fieldPathParam, InstructionTask} from '../../types'
 import type {AssistDocumentContextValue} from '../AssistDocumentContext'
 import {isDocAssistable} from '../RequestRunInstructionProvider'
 import {useStudioAssistDocument} from './useStudioAssistDocument'
@@ -51,7 +51,8 @@ export function useAssistDocumentContextValue(documentId: string, documentType:
     documentId: assistableDocumentId,
     schemaType: documentSchemaType,
   })
-
+  const {syntheticTasks, addSyntheticTask, removeSyntheticTask} =
+    useSyntheticTasks(assistableDocumentId)
   const value: AssistDocumentContextValue = useMemo(() => {
     const base = {
       assistableDocumentId,
@@ -63,6 +64,9 @@ export function useAssistDocumentContextValue(documentId: string, documentType:
       inspector,
       documentOnChange,
       selectedPath,
+      syntheticTasks,
+      addSyntheticTask,
+      removeSyntheticTask,
     }
     if (!assistDocument) {
       return {...base, loading: true, assistDocument: undefined}
@@ -83,7 +87,30 @@ export function useAssistDocumentContextValue(documentId: string, documentType:
     inspector,
     documentOnChange,
     selectedPath,
+    syntheticTasks,
+    addSyntheticTask,
+    removeSyntheticTask,
   ])
 
   return value
 }
+
+function useSyntheticTasks(assistableDocumentId: string) {
+  const [syntheticTasks, setSyntheticTasks] = useState<InstructionTask[]>(() => [])
+  const addSyntheticTask = useCallback((task: InstructionTask) => {
+    setSyntheticTasks((current) => [...current, task])
+  }, [])
+  const removeSyntheticTask = useCallback((task: InstructionTask) => {
+    setSyntheticTasks((current) => current.filter((t) => task._key !== t._key))
+  }, [])
+
+  useEffect(() => {
+    setSyntheticTasks([])
+  }, [assistableDocumentId])
+
+  return {
+    syntheticTasks,
+    addSyntheticTask,
+    removeSyntheticTask,
+  }
+}

package/src/assistLayout/RunInstructionProvider.tsx

@@ -1,5 +1,13 @@
 import {PlayIcon} from '@sanity/icons'
 import {Button, Dialog, Flex, Stack, Text, TextArea, Tooltip} from '@sanity/ui'
+import {FormFieldHeaderText} from 'sanity'
+
+import {getInstructionTitle} from '../helpers/misc'
+import {type UserInputBlock, userInputTypeName} from '../types'
+import {useApiClient, useRunInstructionApi} from '../useApiClient'
+import {useAiAssistanceConfig} from './AiAssistanceConfigContext'
+import type {RunInstructionArgs} from './AssistLayout'
+import {CustomInputResult, GetUserInput} from '../fieldActions/useUserInput'
 import {
   createContext,
   type Dispatch,
@@ -14,24 +22,19 @@ import {
   useRef,
   useState,
 } from 'react'
-import {FormFieldHeaderText} from 'sanity'
-
-import {getInstructionTitle} from '../helpers/misc'
-import {type UserInputBlock, userInputTypeName} from '../types'
-import {useApiClient, useRunInstructionApi} from '../useApiClient'
-import {useAiAssistanceConfig} from './AiAssistanceConfigContext'
-import type {RunInstructionArgs} from './AssistLayout'
 
 type BlockInputs = Record<string, string>
 const NO_INPUT: BlockInputs = {}
 
 export interface RunInstructionContextValue {
   runInstruction: (req: RunInstructionArgs) => void
+  getUserInput: GetUserInput
   instructionLoading: boolean
 }
 
 export const RunInstructionContext = createContext<RunInstructionContextValue>({
   runInstruction: () => {},
+  getUserInput: async () => undefined,
   instructionLoading: false,
 })
 
@@ -53,9 +56,34 @@ export function RunInstructionProvider(props: PropsWithChildren<{}>) {
 
   const [inputs, setInputs] = useState(NO_INPUT)
   const [runRequest, setRunRequest] = useState<
-    (RunInstructionArgs & {userInputBlocks: UserInputBlock[]}) | undefined
+    | (RunInstructionArgs & {userInputBlocks: UserInputBlock[]})
+    | {dialogTitle: string; userInputBlocks: UserInputBlock[]}
+    | undefined
   >()
 
+  const [resolveUserInput, setResolveUserInput] =
+    useState<
+      (
+        value: CustomInputResult[] | PromiseLike<CustomInputResult[] | undefined> | undefined,
+      ) => void
+    >()
+
+  const getUserInput: GetUserInput = useCallback(async ({title, inputs}) => {
+    const userInputBlocks: UserInputBlock[] = inputs.map((input, i) => ({
+      _type: userInputTypeName,
+      _key: input.id ?? `${i}`,
+      message: input.title,
+      description: input.description,
+    }))
+    if (!userInputBlocks.length) {
+      return undefined
+    }
+    setRunRequest({dialogTitle: title, userInputBlocks})
+    return new Promise<CustomInputResult[] | undefined>((resolve) => {
+      setResolveUserInput(() => resolve)
+    })
+  }, [])
+
   const runInstruction = useCallback(
     (req: RunInstructionArgs) => {
       if (loading) {
@@ -89,23 +117,43 @@ export function RunInstructionProvider(props: PropsWithChildren<{}>) {
   const close = useCallback(() => {
     setRunRequest(undefined)
     setInputs(NO_INPUT)
-  }, [])
+    if (resolveUserInput) {
+      resolveUserInput(undefined)
+    }
+    setResolveUserInput(undefined)
+  }, [resolveUserInput])
 
   const runWithInput = useCallback(() => {
     if (runRequest) {
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const {instruction, userTexts, ...request} = runRequest
-      runInstructionRequest({
-        ...request,
-        instructionKey: instruction._key,
-        userTexts: Object.entries(inputs).map(([key, value]) => ({
-          blockKey: key,
-          userInput: value,
-        })),
-      })
+      if ('instruction' in runRequest) {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const {instruction, userTexts, ...request} = runRequest
+        runInstructionRequest({
+          ...request,
+          instructionKey: instruction._key,
+          userTexts: Object.entries(inputs).map(([key, value]) => ({
+            blockKey: key,
+            userInput: value,
+          })),
+        })
+      } else {
+        const userInputs = Object.values(inputs).map((input, i) => {
+          const userInputBlock = runRequest.userInputBlocks[i]
+          return {
+            input: {
+              id: userInputBlock._key,
+              title: userInputBlock.message ?? '',
+              description: userInputBlock.description,
+            },
+            result: input,
+          }
+        })
+        resolveUserInput?.(userInputs)
+        setResolveUserInput(undefined)
+      }
     }
     close()
-  }, [close, runInstructionRequest, runRequest, inputs])
+  }, [close, runInstructionRequest, runRequest, inputs, resolveUserInput])
 
   const open = !!runRequest
 
@@ -128,7 +176,7 @@ export function RunInstructionProvider(props: PropsWithChildren<{}>) {
   )
 
   const contextValue: RunInstructionContextValue = useMemo(
-    () => ({runInstruction, instructionLoading: loading}),
+    () => ({runInstruction, getUserInput, instructionLoading: loading}),
     [runInstruction, loading],
   )
 
@@ -140,7 +188,11 @@ export function RunInstructionProvider(props: PropsWithChildren<{}>) {
           open={open}
           onClose={close}
           width={1}
-          header={getInstructionTitle(runRequest?.instruction)}
+          header={
+            'dialogTitle' in runRequest
+              ? runRequest.dialogTitle
+              : getInstructionTitle(runRequest?.instruction)
+          }
           footer={
             <Flex justify="space-between" padding={2} flex={1}>
               {runDisabled ? (
@@ -178,7 +230,7 @@ export function RunInstructionProvider(props: PropsWithChildren<{}>) {
   )
 }
 
-function UserInput(props: {
+export function UserInput(props: {
   block: UserInputBlock
   inputs: BlockInputs
   setInputs: Dispatch<SetStateAction<BlockInputs>>

package/src/fieldActions/assistFieldActions.tsx

@@ -4,6 +4,7 @@ import {
   type DocumentFieldAction,
   type DocumentFieldActionGroup,
   type DocumentFieldActionItem,
+  stringToPath,
   typed,
   useCurrentUser,
 } from 'sanity'
@@ -24,6 +25,8 @@ import {documentRootKey, fieldPathParam, instructionParam, type StudioInstructio
 import {generateCaptionsActions} from './generateCaptionActions'
 import {generateImagActions} from './generateImageActions'
 import {PrivateIcon} from './PrivateIcon'
+import {AgentActionConditionalPath, useCustomFieldActions} from './customFieldActions'
+import {AgentActionPath} from '@sanity/client/stega'
 
 function node(node: DocumentFieldActionItem | DocumentFieldActionGroup) {
   return node
@@ -48,6 +51,7 @@ export const assistFieldActions: DocumentFieldAction = {
     } = useAssistDocumentContext()
 
     const {value: docValue, formState} = useDocumentPane()
+    const docValueRef = useRef(docValue)
     const formStateRef = useRef(formState)
     formStateRef.current = formState
 
@@ -180,7 +184,35 @@ export const assistFieldActions: DocumentFieldAction = {
       imageGenAction,
     ])
 
-    const instructionsLength = instructions?.length || 0
+    const getDocumentValue = useCallback(() => {
+      return docValueRef.current
+    }, [])
+
+    const getConditionalPaths: () => AgentActionConditionalPath[] = useCallback(() => {
+      return (formStateRef.current ? getConditionalMembers(formStateRef.current) : []).flatMap(
+        (cm) => {
+          const path = stringToPath(cm.path)
+          if (path.some((s) => typeof s === 'number')) {
+            //agent actions does not support indexed paths
+            return []
+          }
+          return {
+            ...cm,
+            path: path as AgentActionPath,
+          }
+        },
+      )
+    }, [])
+
+    const customActions = useCustomFieldActions({
+      actionType: props.path.length ? 'field' : 'document',
+      documentIdForAction: assistableDocumentId,
+      schemaType,
+      documentSchemaType,
+      path: props.path,
+      getDocumentValue,
+      getConditionalPaths,
+    })
 
     const manageInstructionsItem = useMemo(
       () =>
@@ -203,6 +235,7 @@ export const assistFieldActions: DocumentFieldAction = {
           children: [
             runInstructionsGroup,
             translateAction,
+            ...customActions,
             assistSupported && manageInstructionsItem,
           ]
             .filter((c): c is DocumentFieldActionItem | DocumentFieldActionGroup => !!c)
@@ -219,6 +252,7 @@ export const assistFieldActions: DocumentFieldAction = {
         imageCaptionAction,
         translateAction,
         imageGenAction,
+        customActions,
       ],
     )
 
@@ -237,7 +271,13 @@ export const assistFieldActions: DocumentFieldAction = {
     )
 
     // If there are no instructions, we don't want to render the group
-    if (instructionsLength === 0 && !imageCaptionAction && !translateAction && !imageGenAction) {
+    if (
+      !instructions?.length &&
+      !imageCaptionAction &&
+      !translateAction &&
+      !imageGenAction &&
+      !customActions.length
+    ) {
       return emptyAction
     }
 

package/src/fieldActions/customFieldActions.tsx

@@ -0,0 +1,304 @@
+import {
+  DocumentFieldActionDivider,
+  DocumentFieldActionGroup,
+  DocumentFieldActionItem,
+  DocumentFieldActionNode,
+  ObjectSchemaType,
+  SanityDocumentLike,
+  useWorkspaceSchemaId,
+} from 'sanity'
+import {Path, SchemaType} from '@sanity/types'
+import {useMemo} from 'react'
+import {useAiAssistanceConfig} from '../assistLayout/AiAssistanceConfigContext'
+import {ToastParams, useToast} from '@sanity/ui'
+import {AgentActionPath} from '@sanity/client/stega'
+import {useAssistDocumentContext} from '../assistDocument/AssistDocumentContext'
+import {
+  documentRootKey,
+  fieldPresenceTypeName,
+  InstructionTask,
+  instructionTaskTypeName,
+} from '../types'
+import {randomKey} from '../_lib/randomKey'
+
+export interface AgentActionConditionalPath {
+  path: AgentActionPath
+  readOnly: boolean
+  hidden: boolean
+}
+
+export 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
+}
+
+export type AssistFieldActionNode =
+  | AssistFieldActionItem
+  | AssistFieldActionGroup
+  | DocumentFieldActionDivider
+
+export type AssistFieldActionItem = Omit<
+  DocumentFieldActionItem,
+  'renderAsButton' | 'selected' | 'onAction'
+> & {
+  onAction: () => void | Promise<void>
+}
+
+export type AssistFieldActionGroup = Omit<
+  DocumentFieldActionGroup,
+  'renderAsButton' | 'expanded' | 'children'
+> & {
+  children: AssistFieldActionNode[]
+}
+
+type PushToast = (params: ToastParams) => string
+
+export function defineAssistFieldAction(
+  action: Omit<AssistFieldActionItem, 'type'>,
+): AssistFieldActionItem {
+  return {
+    ...action,
+    type: 'action',
+  }
+}
+
+export function defineFieldActionDivider(): DocumentFieldActionDivider {
+  return {
+    type: 'divider',
+  }
+}
+
+export function defineAssistFieldActionGroup(
+  group: Omit<AssistFieldActionGroup, 'type'>,
+): AssistFieldActionGroup {
+  return {
+    ...group,
+    type: 'group',
+  }
+}
+
+export function useCustomFieldActions(
+  props: Omit<AssistFieldActionProps, 'schemaId' | 'path'> & {path: Path},
+) {
+  const {
+    config: {fieldActions},
+  } = useAiAssistanceConfig()
+  const {addSyntheticTask, removeSyntheticTask} = useAssistDocumentContext()
+
+  const schemaId = useWorkspaceSchemaId()
+  const {push: pushToast} = useToast()
+  const configActions = fieldActions?.useFieldActions?.({
+    ...props,
+    schemaId,
+    path: props.path as AgentActionPath,
+  })
+
+  return useMemo(() => {
+    const title = fieldActions?.title
+    const customActions = configActions?.map((node) => {
+      return createSafeNode({
+        node,
+        pushToast,
+        addSyntheticTask,
+        removeSyntheticTask,
+      })
+    })
+    const onlyGroups =
+      customActions?.length && customActions?.every((node) => node.type === 'group')
+    const groups = customActions?.length
+      ? onlyGroups
+        ? customActions
+        : [
+            {
+              type: 'group',
+              title: title || 'Custom actions',
+              children: customActions,
+              expanded: true,
+            } satisfies DocumentFieldActionGroup,
+          ]
+      : []
+    return groups ?? []
+  }, [configActions, fieldActions, pushToast])
+}
+
+function createSafeNode(args: {
+  node: AssistFieldActionNode
+  pushToast: PushToast
+  addSyntheticTask: (task: InstructionTask) => void
+  removeSyntheticTask: (task: InstructionTask) => void
+}): DocumentFieldActionNode {
+  const {node} = args
+  switch (node.type) {
+    case 'action':
+      return createSafeAction({...args, action: node})
+    case 'group':
+      return {
+        ...node,
+        renderAsButton: false,
+        expanded: true,
+        children: node.children?.map((child) => createSafeNode({...args, node: child})),
+      }
+    case 'divider':
+    default:
+      return node
+  }
+}
+
+function createSafeAction(args: {
+  action: AssistFieldActionItem
+  pushToast: PushToast
+  addSyntheticTask: (task: InstructionTask) => void
+  removeSyntheticTask: (task: InstructionTask) => void
+}) {
+  const {action, pushToast, addSyntheticTask, removeSyntheticTask} = args
+  return {
+    ...action,
+    onAction: () => {
+      async function runAction() {
+        const task: InstructionTask = {
+          _type: instructionTaskTypeName,
+          _key: randomKey(12),
+          started: new Date().toISOString(),
+          presence: [
+            {
+              _type: fieldPresenceTypeName,
+              _key: randomKey(12),
+              path: documentRootKey,
+              started: new Date().toISOString(),
+            },
+          ],
+        }
+        try {
+          addSyntheticTask(task)
+          const actionResult = action.onAction?.()
+          if (actionResult instanceof Promise) {
+            await actionResult
+          }
+        } catch (err: any) {
+          console.error('Failed to execute action', action, err)
+          pushToast({
+            title: 'Failed to execute action',
+            description: err?.message,
+            status: 'error',
+          })
+        } finally {
+          removeSyntheticTask(task)
+        }
+      }
+      runAction()
+    },
+    renderAsButton: false,
+    selected: false,
+  }
+}