@sanity/assist 4.1.0 → 4.3.0

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,
+  }
+}

package/src/fieldActions/useUserInput.ts

@@ -0,0 +1,107 @@
+import {useRunInstruction} from '../assistLayout/RunInstructionProvider'
+
+export type GetUserInput = (args: {
+  /**
+   * Dialog title
+   */
+  title: string
+  /**
+   * One titled input per array item
+   */
+  inputs: CustomInput[]
+}) => Promise<CustomInputResult[] | undefined>
+
+/**
+ *
+ */
+export 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 type CustomInputResult = {
+  /**
+   * Identifies which custom input the `result`belongs to
+   */
+  input: CustomInput
+
+  /**
+   * The text provided by the user in the input
+   */
+  result: string
+}
+
+/**
+ * `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 function useUserInput(): GetUserInput {
+  const {getUserInput} = useRunInstruction()
+  return getUserInput
+}

package/src/helpers/typeUtils.ts

@@ -18,13 +18,23 @@ export function isImage(schemaType: SchemaType) {
   return isType(schemaType, 'image')
 }
 
-export function getDescriptionFieldOption(schemaType: SchemaType | undefined): string | undefined {
+export function getDescriptionFieldOption(
+  schemaType: SchemaType | undefined,
+): {path: string; updateOnImageChange: boolean} | undefined {
   if (!schemaType) {
     return undefined
   }
   const descriptionField = (schemaType.options as ImageOptions)?.aiAssist?.imageDescriptionField
-  if (descriptionField) {
-    return descriptionField
+  if (typeof descriptionField === 'string') {
+    return {
+      path: descriptionField,
+      updateOnImageChange: true,
+    }
+  } else if (descriptionField) {
+    return {
+      path: descriptionField.path,
+      updateOnImageChange: descriptionField.updateOnImageChange ?? true,
+    }
   }
   return getDescriptionFieldOption(schemaType.type)
 }

package/src/index.ts

@@ -5,3 +5,20 @@ export {defaultLanguageOutputs} from './translate/paths'
 export * from './translate/types'
 export {contextDocumentTypeName} from './types'
 export * from './assistTypes'
+
+export {
+  type AssistFieldActionProps,
+  type AssistFieldActionGroup,
+  type AssistFieldActionItem,
+  type AssistFieldActionNode,
+  defineAssistFieldAction,
+  defineFieldActionDivider,
+  defineAssistFieldActionGroup,
+} from './fieldActions/customFieldActions'
+
+export {
+  type GetUserInput,
+  type CustomInput,
+  type CustomInputResult,
+  useUserInput,
+} from './fieldActions/useUserInput'

package/src/plugin.tsx

@@ -21,6 +21,7 @@ import {createAssistDocumentPresence} from './presence/AssistDocumentPresence'
 import {schemaTypes} from './schemas'
 import {TranslationConfig} from './translate/types'
 import {assistDocumentTypeName, AssistPreset} from './types'
+import {AssistFieldActionNode, AssistFieldActionProps} from './fieldActions/customFieldActions'
 
 export interface AssistPluginConfig {
   translate?: TranslationConfig
@@ -30,6 +31,11 @@ export interface AssistPluginConfig {
    */
   assist?: AssistConfig
 
+  fieldActions?: {
+    title?: string
+    useFieldActions?: (props: AssistFieldActionProps) => AssistFieldActionNode[]
+  }
+
   /**
    * @internal
    */

package/src/presence/AssistDocumentPresence.tsx

@@ -13,9 +13,9 @@ export function createAssistDocumentPresence(documentId: string | undefined) {
 }
 
 function AssistDocumentPresence() {
-  const {assistDocument} = useAssistDocumentContext()
+  const {assistDocument, syntheticTasks} = useAssistDocumentContext()
   const anyPresence = useMemo(() => {
-    const anyPresence = assistDocument?.tasks
+    const anyPresence = [...(assistDocument?.tasks ?? []), ...(syntheticTasks ?? [])]
       ?.filter((run) => !run.ended && !run.reason)
       ?.flatMap((run) => run.presence ?? [])
       .find((f) => f.started && new Date().getTime() - new Date(f.started).getTime() < 30000)
@@ -36,7 +36,7 @@ function AssistDocumentPresence() {
           [],
         )
       : undefined
-  }, [assistDocument?.tasks])
+  }, [assistDocument?.tasks, syntheticTasks])
 
   return (
     <Card>

package/src/schemas/typeDefExtensions.ts

@@ -90,7 +90,18 @@ declare module 'sanity' {
        * })
        * ```
        */
-      imageDescriptionField?: string
+      imageDescriptionField?:
+        | string
+        | {
+            path: string
+            /**
+             * When updateOnImageChange is true (or undefined), whenever the
+             * image asset changes, imageDescriptionField will be regenerated.
+             *
+             * default:  true
+             * */
+            updateOnImageChange?: boolean
+          }
     }
   }
   interface NumberOptions extends AssistOptions {}