@sanity/assist 3.2.2 → 4.0.1

package/README.md

@@ -12,11 +12,13 @@
   - [Enabling the AI Assist API](#enabling-the-ai-assist-api)
   - [Permissions](#permissions)
   - [Conditional user access](#conditional-user-access)
+  - [Assist configuration](#assist-configuration-optional)
 - [Schema configuration](#schema-configuration)
   - [Disable AI Assist for a schema type](#disable-ai-assist-for-a-schema-type)
   - [Disable for a field](#disable-for-a-field)
   - [Disable for an array type](#disable-for-an-array-type)
   - [Unsupported types](#unsupported-types)
+  - [Date and datetime](#date-and-datetime)
   - [Hidden and readOnly fields](#hidden-and-readonly-fields)
   - [Reference support](#reference-support)
   - [Troubleshooting](#troubleshooting)
@@ -152,6 +154,26 @@ function isAiAssistAllowed(user?: CurrentUser | null) {
 }
 ```
 
+### Assist configuration (optional)
+
+```ts
+assist({
+  // Showing default values
+  assist: {
+    localeSettings: () => Intl.DateTimeFormat().resolvedOptions(),
+    maxPathDepth: 4,
+    temperature: 0.3
+  },
+  translate: { /* see sections about document and field translation */}
+})
+```
+
+- `localeSettings`: See section on [date and datetime](#date-and-datetime)
+- `maxPathDepth`: The max depth for document paths AI Assist will write to.
+- `temperature`: Influences how much the output of an instruction will vary between runs.
+
+For more details, please review the TSDocs of the individual config parameters in [assistTypes.ts](./src/assistTypes.ts)
+
 ## Schema configuration
 
 By default, most string, object, and array field types (including Portable Text!) have AI writing assistance enabled. Your assistant can write to all compatible fields that it detects.
@@ -215,11 +237,6 @@ defineType({
 
 The following types are not supported, and behave as excluded types:
 
-- [Number](https://www.sanity.io/docs/number-type)
-- [Slug](https://www.sanity.io/docs/slug-type)
-- [Url](https://www.sanity.io/docs/url-type)
-- [Date](https://www.sanity.io/docs/date-type)
-- [Datetime](https://www.sanity.io/docs/datetime-type)
 - [Image](https://www.sanity.io/docs/image-type) (supported when image has custom fields)
 - [File](https://www.sanity.io/docs/file-type) (never supported, even when file has custom fields)
 - [Reference](https://www.sanity.io/docs/reference-type) (supported when configured with embeddingsIndex)
@@ -229,6 +246,42 @@ Fields with these types will not be changed by the assistant, do not have AI Ass
 Objects where all fields are excluded or unsupported and arrays where all member types are excluded or unsupported
 will also be excluded.
 
+### Date and datetime
+- [Date](https://www.sanity.io/docs/date-type)
+- [Datetime](https://www.sanity.io/docs/datetime-type)
+
+Starting from v3.0.0, AI Assist can write to date and datetime fields. Instructions can use language like "tomorrow at noon" or
+"next year", and when Assist writes to the field, it will be converted to a field-compatible value.
+
+Language about time is locale and timeZone dependant. By default instructions will use the locale and timezone provided
+by the browser (`Intl.DateTimeFormat().resolvedOptions()`).
+
+Alternatively, you can configure the plugin per user with an `assist.localeSettings` function that should return `LocaleSettings`.
+
+##### Example
+```ts
+assist({
+  assist: {
+    localeSettings: ({currentUser, defaultSettings}) => {
+      if (currentUser.roles.includes('admin')) {
+        // forces locale and timeZone for admins
+        return {
+          locale: 'en-US',
+          timeZone: 'America/New_York'
+        }
+      }
+      // defaultSettings is the same as using:
+      // const {locale, timeZone} = Intl.DateTimeFormat().resolvedOptions()
+      return defaultSettings
+    }
+  }
+})
+```
+
+For a list of allowed values for these parameters, see the following resources: 
+- `locale`: [Mozilla on Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#getcanonicalocales)
+- `timeZone`: [Wiki on time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
+
 ### Hidden and readOnly fields
 
 In AI Assist 2.0 and later, conditionally `hidden` and `readOnly` fields can have instructions.

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import {CurrentUser} from 'sanity'
 import {JSX as JSX_2} from 'react/jsx-runtime'
 import {Path} from 'sanity'
 import {Plugin as Plugin_2} from 'sanity'
@@ -10,6 +11,56 @@ import {SchemaType} from 'sanity'
 
 export declare const assist: Plugin_2<void | AssistPluginConfig>
 
+export declare interface AssistConfig {
+  /**
+   * As of v3.0 Assist can write to date and datetime fields.
+   *
+   * If this function is omitted from config, the plugin will use the default timeZone and locale
+   * in the browser:
+   *
+   * ```ts
+   * const {timeZone, locale} = Intl.DateTimeFormat().resolvedOptions()
+   * ```
+   *
+   * The function will be called any time an instruction runs.
+   *
+   * @see #LocaleSettings.locale
+   * @see #LocaleSettings.timeZone
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#getcanonicalocales
+   * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+   */
+  localeSettings?: (context: LocaleSettingsContext) => LocaleSettings
+  /**
+   * The max depth for document paths AI Assist will write to.
+   *
+   * Depth is based on field path segments:
+   * - `title` has depth 1
+   * - `array[_key="no"].title` has depth 3
+   *
+   * Be careful not to set this too high in studios with recursive document schemas, as it could have
+   * negative impact on performance.
+   *
+   * Depth will be counted from the field the instruction is run from. For example, if an instruction
+   * is attached to depth 6, the count starts from there (at 0, not at 6).
+   *
+   * Default: 4
+   */
+  maxPathDepth?: number
+  /**
+   * Influences how much the output of an instruction will vary.
+   *
+   * Min: 0 – re-running an instruction will often produce the same outcomes
+   * Max: 1 – re-running an instruction can produce wildly different outcomes
+   *
+   * This parameter applies to _all_ instructions in the studio.
+   *
+   * Prior to v3.0, this defaulted to 0
+   *
+   * Default: 0.3
+   */
+  temperature?: number
+}
+
 export declare interface AssistOptions {
   aiAssist?: {
     /** Set to true to disable assistance for this field or type */
@@ -24,6 +75,10 @@ export declare interface AssistOptions {
 
 declare interface AssistPluginConfig {
   translate?: TranslationConfig
+  /**
+   * Config that affects all instructions
+   */
+  assist?: AssistConfig
   /**
    * @internal
    */
@@ -210,6 +265,35 @@ export declare type LanguageCallback = (
   selectedLanguageParams: Record<string, unknown>,
 ) => Promise<Language[]>
 
+export declare interface LocaleSettings {
+  /**
+   * A valid Unicode BCP 47 locale identifier used to interpret and format
+   * natural language inputs and date output. Examples include "en-US", "fr-FR", or "ja-JP".
+   *
+   * This affects how phrases like "next Friday" or "in two weeks" are parsed,
+   * and how resulting dates are presented (e.g., 12-hour vs 24-hour format).
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#getcanonicalocales
+   */
+  locale: string
+  /**
+   * A valid IANA time zone identifier used to resolve relative and absolute
+   * date expressions to a specific point in time. Examples include
+   * "America/New_York", "Europe/Paris", or "Asia/Tokyo".
+   *
+   * This ensures phrases like "tomorrow at 9am" are interpreted correctly
+   * based on the user's local time.
+   *
+   * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+   */
+  timeZone: string
+}
+
+export declare interface LocaleSettingsContext {
+  user: CurrentUser
+  defaultSettings: LocaleSettings
+}
+
 declare interface OutputFieldItem {
   _type: typeof outputFieldTypeName
   _key: string

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import {CurrentUser} from 'sanity'
 import {JSX as JSX_2} from 'react/jsx-runtime'
 import {Path} from 'sanity'
 import {Plugin as Plugin_2} from 'sanity'
@@ -10,6 +11,56 @@ import {SchemaType} from 'sanity'
 
 export declare const assist: Plugin_2<void | AssistPluginConfig>
 
+export declare interface AssistConfig {
+  /**
+   * As of v3.0 Assist can write to date and datetime fields.
+   *
+   * If this function is omitted from config, the plugin will use the default timeZone and locale
+   * in the browser:
+   *
+   * ```ts
+   * const {timeZone, locale} = Intl.DateTimeFormat().resolvedOptions()
+   * ```
+   *
+   * The function will be called any time an instruction runs.
+   *
+   * @see #LocaleSettings.locale
+   * @see #LocaleSettings.timeZone
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#getcanonicalocales
+   * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+   */
+  localeSettings?: (context: LocaleSettingsContext) => LocaleSettings
+  /**
+   * The max depth for document paths AI Assist will write to.
+   *
+   * Depth is based on field path segments:
+   * - `title` has depth 1
+   * - `array[_key="no"].title` has depth 3
+   *
+   * Be careful not to set this too high in studios with recursive document schemas, as it could have
+   * negative impact on performance.
+   *
+   * Depth will be counted from the field the instruction is run from. For example, if an instruction
+   * is attached to depth 6, the count starts from there (at 0, not at 6).
+   *
+   * Default: 4
+   */
+  maxPathDepth?: number
+  /**
+   * Influences how much the output of an instruction will vary.
+   *
+   * Min: 0 – re-running an instruction will often produce the same outcomes
+   * Max: 1 – re-running an instruction can produce wildly different outcomes
+   *
+   * This parameter applies to _all_ instructions in the studio.
+   *
+   * Prior to v3.0, this defaulted to 0
+   *
+   * Default: 0.3
+   */
+  temperature?: number
+}
+
 export declare interface AssistOptions {
   aiAssist?: {
     /** Set to true to disable assistance for this field or type */
@@ -24,6 +75,10 @@ export declare interface AssistOptions {
 
 declare interface AssistPluginConfig {
   translate?: TranslationConfig
+  /**
+   * Config that affects all instructions
+   */
+  assist?: AssistConfig
   /**
    * @internal
    */
@@ -210,6 +265,35 @@ export declare type LanguageCallback = (
   selectedLanguageParams: Record<string, unknown>,
 ) => Promise<Language[]>
 
+export declare interface LocaleSettings {
+  /**
+   * A valid Unicode BCP 47 locale identifier used to interpret and format
+   * natural language inputs and date output. Examples include "en-US", "fr-FR", or "ja-JP".
+   *
+   * This affects how phrases like "next Friday" or "in two weeks" are parsed,
+   * and how resulting dates are presented (e.g., 12-hour vs 24-hour format).
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#getcanonicalocales
+   */
+  locale: string
+  /**
+   * A valid IANA time zone identifier used to resolve relative and absolute
+   * date expressions to a specific point in time. Examples include
+   * "America/New_York", "Europe/Paris", or "Asia/Tokyo".
+   *
+   * This ensures phrases like "tomorrow at 9am" are interpreted correctly
+   * based on the user's local time.
+   *
+   * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+   */
+  timeZone: string
+}
+
+export declare interface LocaleSettingsContext {
+  user: CurrentUser
+  defaultSettings: LocaleSettings
+}
+
 declare interface OutputFieldItem {
   _type: typeof outputFieldTypeName
   _key: string

package/dist/index.esm.js

@@ -236,7 +236,7 @@ function isDisabled(type) {
   return !isSchemaAssistEnabled(type) || isUnsupportedType(type);
 }
 function isUnsupportedType(type) {
-  return type.jsonType === "number" || type.name === "sanity.imageCrop" || type.name === "sanity.imageHotspot" || isType(type, "globalDocumentReference") || isType(type, "reference") && !type?.options?.aiAssist?.embeddingsIndex || isType(type, "crossDatasetReference") || isType(type, "slug") || isType(type, "url") || isType(type, "date") || isType(type, "datetime") || isType(type, "file");
+  return type.name === "sanity.imageCrop" || type.name === "sanity.imageHotspot" || isType(type, "globalDocumentReference") || isType(type, "reference") && !type?.options?.aiAssist?.embeddingsIndex || isType(type, "crossDatasetReference") || isType(type, "file");
 }
 const FirstAssistedPathContext = createContext(void 0);
 function FirstAssistedPathProvider(props) {
@@ -466,6 +466,39 @@ function useAiPaneRouter() {
     [paneRouter]
   );
 }
+const AiAssistanceConfigContext = createContext({});
+function useAiAssistanceConfig() {
+  const context = useContext(AiAssistanceConfigContext);
+  if (!context)
+    throw new Error("Missing AiAssistanceConfigContext");
+  return context;
+}
+function AiAssistanceConfigProvider(props) {
+  const [status, setStatus] = useState(), [error, setError] = useState(), apiClient = useApiClient(props.config?.__customApiClient), { getInstructStatus, loading: statusLoading } = useGetInstructStatus(apiClient), { initInstruct, loading: initLoading } = useInitInstruct(apiClient);
+  useEffect(() => {
+    getInstructStatus().then((s) => setStatus(s)).catch((e) => {
+      console.error(e), setError(e);
+    });
+  }, [getInstructStatus]);
+  const init = useCallback(async () => {
+    setError(void 0);
+    try {
+      await initInstruct();
+      const status2 = await getInstructStatus();
+      setStatus(status2);
+    } catch (e) {
+      console.error("Failed to init ai assistance", e), setError(e);
+    }
+  }, [initInstruct, getInstructStatus, setStatus]), { config, children } = props, context = useMemo(() => ({
+    config,
+    status,
+    statusLoading,
+    init,
+    initLoading,
+    error
+  }), [config, status, init, statusLoading, initLoading, error]);
+  return /* @__PURE__ */ jsx(AiAssistanceConfigContext.Provider, { value: context, children });
+}
 const hiddenTypes = [
   "any",
   "array",
@@ -589,12 +622,12 @@ function refToTypeNames(type) {
 function removeUndef(obj) {
   return Object.keys(obj).forEach((key) => obj[key] === void 0 ? delete obj[key] : {}), obj;
 }
-const basePath = "/assist/tasks/instruction";
+const basePath = "/assist/tasks/instruction", API_VERSION_WITH_EXTENDED_TYPES = "2025-04-01";
 function canUseAssist(status) {
   return status?.enabled && status.initialized && status.validToken;
 }
 function useApiClient(customApiClient) {
-  const client = useClient({ apiVersion: "2023-06-05" });
+  const client = useClient({ apiVersion: API_VERSION_WITH_EXTENDED_TYPES });
   return useMemo(
     () => customApiClient ? customApiClient(client) : client,
     [client, customApiClient]
@@ -738,25 +771,40 @@ function useInitInstruct(apiClient) {
   };
 }
 function useRunInstructionApi(apiClient) {
-  const toast = useToast(), [loading, setLoading] = useState(!1), user = useCurrentUser(), schema = useSchema(), types = useMemo(() => serializeSchema(schema, { leanFormat: !0 }), [schema]), runInstruction = useCallback(
-    (request) => (setLoading(!0), apiClient.request({
-      method: "POST",
-      url: `${basePath}/${apiClient.config().dataset}?projectId=${apiClient.config().projectId}`,
-      body: {
-        ...request,
-        types,
-        userId: user?.id
+  const toast = useToast(), [loading, setLoading] = useState(!1), user = useCurrentUser(), schema = useSchema(), types = useMemo(() => serializeSchema(schema, { leanFormat: !0 }), [schema]), {
+    config: { assist: assistConfig }
+  } = useAiAssistanceConfig(), runInstruction = useCallback(
+    (request) => {
+      if (!user) {
+        toast.push({
+          status: "error",
+          title: "Unable to get user for instruction."
+        });
+        return;
       }
-    }).catch((e) => {
-      throw toast.push({
-        status: "error",
-        title: "Instruction failed",
-        description: e.message
-      }), e;
-    }).finally(() => {
-      setLoading(!1);
-    })),
-    [apiClient, types, user, toast]
+      setLoading(!0);
+      const { timeZone, locale } = Intl.DateTimeFormat().resolvedOptions(), defaultLocaleSettings = { timeZone, locale }, localeSettings = assistConfig?.localeSettings?.({ user, defaultSettings: defaultLocaleSettings }) ?? defaultLocaleSettings;
+      return apiClient.request({
+        method: "POST",
+        url: `${basePath}/${apiClient.config().dataset}?projectId=${apiClient.config().projectId}`,
+        body: {
+          ...request,
+          types,
+          userId: user?.id,
+          localeSettings,
+          maxPathDepth: assistConfig?.maxPathDepth
+        }
+      }).catch((e) => {
+        throw toast.push({
+          status: "error",
+          title: "Instruction failed",
+          description: e.message
+        }), e;
+      }).finally(() => {
+        setLoading(!1);
+      });
+    },
+    [apiClient, types, user, toast, assistConfig]
   );
   return useMemo(
     () => ({
@@ -766,39 +814,6 @@ function useRunInstructionApi(apiClient) {
     [runInstruction, loading]
   );
 }
-const AiAssistanceConfigContext = createContext({});
-function useAiAssistanceConfig() {
-  const context = useContext(AiAssistanceConfigContext);
-  if (!context)
-    throw new Error("Missing AiAssistanceConfigContext");
-  return context;
-}
-function AiAssistanceConfigProvider(props) {
-  const [status, setStatus] = useState(), [error, setError] = useState(), apiClient = useApiClient(props.config?.__customApiClient), { getInstructStatus, loading: statusLoading } = useGetInstructStatus(apiClient), { initInstruct, loading: initLoading } = useInitInstruct(apiClient);
-  useEffect(() => {
-    getInstructStatus().then((s) => setStatus(s)).catch((e) => {
-      console.error(e), setError(e);
-    });
-  }, [getInstructStatus]);
-  const init = useCallback(async () => {
-    setError(void 0);
-    try {
-      await initInstruct();
-      const status2 = await getInstructStatus();
-      setStatus(status2);
-    } catch (e) {
-      console.error("Failed to init ai assistance", e), setError(e);
-    }
-  }, [initInstruct, getInstructStatus, setStatus]), { config, children } = props, context = useMemo(() => ({
-    config,
-    status,
-    statusLoading,
-    init,
-    initLoading,
-    error
-  }), [config, status, init, statusLoading, initLoading, error]);
-  return /* @__PURE__ */ jsx(AiAssistanceConfigContext.Provider, { value: context, children });
-}
 const NO_INPUT = {}, RunInstructionContext = createContext({
   runInstruction: () => {
   },
@@ -967,10 +982,7 @@ function useAssistDocumentContextValue(documentId, documentType) {
     // @ts-ignore this is a valid option available in `corel` - Remove after corel is merged to next
     selectedReleaseId,
     editState
-  } = useDocumentPane(), { draft, published, version } = editState || {};
-  let assistableDocumentId = version?._id || draft?._id || published?._id;
-  assistableDocumentId || (assistableDocumentId = selectedReleaseId ? getVersionId(documentId, selectedReleaseId) : documentSchemaType.liveEdit ? documentId : getDraftId(documentId));
-  const documentIsNew = selectedReleaseId ? !version?._id : !draft?._id && !published?._id, documentIsAssistable = selectedReleaseId ? !!version : isDocAssistable(documentSchemaType, published, draft), { params } = useAiPaneRouter(), selectedPath = params[fieldPathParam], assistDocument = useStudioAssistDocument({
+  } = 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
   });
@@ -1975,7 +1987,7 @@ function AssistInspector(props) {
               mode: "ghost",
               disabled: isEmptyPrompt || instructionLoading,
               fontSize: 1,
-              icon: instructionLoading ? /* @__PURE__ */ jsx(Spinner, {}) : PlayIcon,
+              icon: instructionLoading ? /* @__PURE__ */ jsx(Spinner, { style: { marginTop: 3 } }) : PlayIcon,
               onClick: runCurrentInstruction,
               padding: 3,
               text: "Run instruction"
@@ -3871,11 +3883,19 @@ const instructionForm = [
   instructionTask,
   contextDocumentSchema
 ], assist = definePlugin((config) => {
-  const configWithDefaults = config ?? {}, styleguide = configWithDefaults.translate?.styleguide || "";
+  const configWithDefaults = config ?? {}, styleguide = configWithDefaults.translate?.styleguide || "", maxPathDepth = configWithDefaults.assist?.maxPathDepth, temperature = configWithDefaults.assist?.temperature;
   if (styleguide.length > 2e3)
     throw new Error(
       `[${packageName}]: \`translate.styleguide\` value is too long. It must be 2000 characters or less, was ${styleguide.length} characters`
     );
+  if (maxPathDepth !== void 0 && (maxPathDepth < 1 || maxPathDepth > 12))
+    throw new Error(
+      `[${packageName}]: \`assist.maxPathDepth\` must be be in the range [1,12] inclusive, but was ${maxPathDepth}`
+    );
+  if (temperature !== void 0 && (temperature < 0 || temperature > 1))
+    throw new Error(
+      `[${packageName}]: \`assist.maxPathDepth\` must be be in the range [0,1] inclusive, but was ${temperature}`
+    );
   return {
     name: packageName,
     handlesGDR: !0,