datocms-plugin-sdk 2.1.0-alpha.0 → 2.1.0-alpha.1

package/manifest.json

@@ -94,6 +94,29 @@
         "lineNumber": 19
       }
     },
+    "schemaItemTypeDropdownActions": {
+      "name": "schemaItemTypeDropdownActions",
+      "comment": {
+        "markdownText": "Use this function to define custom actions (or groups of actions) for a model/block model in the Schema section.\n\nThe `executeSchemaItemTypeDropdownAction()` hook will be triggered once the user\nclicks on one of the defined actions.",
+        "tag": "dropdownActions"
+      },
+      "nonCtxArguments": [
+        {
+          "name": "itemType",
+          "typeName": "ItemType"
+        }
+      ],
+      "ctxArgument": {
+        "type": "Ctx",
+        "additionalProperties": [],
+        "additionalMethods": []
+      },
+      "returnType": "Array<DropdownAction | DropdownActionGroup>",
+      "location": {
+        "filePath": "src/hooks/schemaItemTypeDropdownActions.ts",
+        "lineNumber": 16
+      }
+    },
     "renderUploadSidebarPanel": {
       "name": "renderUploadSidebarPanel",
       "comment": {
@@ -236,6 +259,16 @@
                   "lineNumber": 19
                 },
                 "type": "string"
+              },
+              "location": {
+                "comment": {
+                  "markdownText": "Current page location."
+                },
+                "location": {
+                  "filePath": "src/hooks/renderPage.ts",
+                  "lineNumber": 22
+                },
+                "type": "{\n      pathname: string;\n      search: string;\n      hash: string;\n    }"
               }
             }
           }
@@ -1583,7 +1616,7 @@
     "onBeforeItemUpsert": {
       "name": "onBeforeItemUpsert",
       "comment": {
-        "markdownText": "This function will be called before saving a new version of a record. You\ncan stop the action by returning `false`.",
+        "markdownText": "This hook is called when the user attempts to save a record. You can use it to block record saving.\n\nIf you return `false`, the record will NOT be saved. A small on-page error will say \"A plugin blocked the action\".\nHowever, for better UX, consider also using `ctx.alert()` to better explain to the user why their save was blocked.\n\nIf you return `true`, the save will proceed as normal.\n\nThis hook runs BEFORE serverside validation. You can use it to do your own additional validation before returning.\nClientside validations are not affected by this hook, since those occur on individual fields' `onBlur()` events.",
         "tag": "beforeHooks"
       },
       "nonCtxArguments": [
@@ -1594,13 +1627,33 @@
       ],
       "ctxArgument": {
         "type": "Ctx",
-        "additionalProperties": [],
-        "additionalMethods": []
+        "additionalProperties": [
+          {
+            "items": {}
+          }
+        ],
+        "additionalMethods": [
+          {
+            "items": {
+              "scrollToField": {
+                "comment": {
+                  "markdownText": "Smoothly navigates to a specific field in the form. If the field is\nlocalized it will switch language tab and then navigate to the chosen\nfield.",
+                  "example": "const fieldPath = prompt(\n  'Please insert the path of a field in the form',\n  ctx.fieldPath,\n);\n\nawait ctx.scrollToField(fieldPath);"
+                },
+                "location": {
+                  "filePath": "src/hooks/onBeforeItemUpsert.ts",
+                  "lineNumber": 47
+                },
+                "type": "(path: string, locale?: string) => Promise<void>"
+              }
+            }
+          }
+        ]
       },
       "returnType": "MaybePromise<boolean>",
       "location": {
         "filePath": "src/hooks/onBeforeItemUpsert.ts",
-        "lineNumber": 15
+        "lineNumber": 22
       }
     },
     "manualFieldExtensions": {
@@ -2114,6 +2167,45 @@
         "lineNumber": 13
       }
     },
+    "executeSchemaItemTypeDropdownAction": {
+      "name": "executeSchemaItemTypeDropdownAction",
+      "comment": {
+        "markdownText": "Use this function to execute a particular dropdown action defined via\nthe `schemaItemTypeDropdownActions()` hook.",
+        "tag": "dropdownActions"
+      },
+      "nonCtxArguments": [
+        {
+          "name": "actionId",
+          "typeName": "string"
+        },
+        {
+          "name": "itemType",
+          "typeName": "ItemType"
+        }
+      ],
+      "ctxArgument": {
+        "type": "Ctx",
+        "additionalProperties": [
+          {
+            "items": {
+              "parameters": {
+                "location": {
+                  "filePath": "src/hooks/executeSchemaItemTypeDropdownAction.ts",
+                  "lineNumber": 23
+                },
+                "type": "Record<string, unknown> | undefined"
+              }
+            }
+          }
+        ],
+        "additionalMethods": []
+      },
+      "returnType": "Promise<void>",
+      "location": {
+        "filePath": "src/hooks/executeSchemaItemTypeDropdownAction.ts",
+        "lineNumber": 13
+      }
+    },
     "executeItemsDropdownAction": {
       "name": "executeItemsDropdownAction",
       "comment": {
@@ -2840,13 +2932,23 @@
             },
             "type": "string"
           },
+          "isEnvironmentPrimary": {
+            "comment": {
+              "markdownText": "Whether the current environment is the primary one."
+            },
+            "location": {
+              "filePath": "src/ctx/base.ts",
+              "lineNumber": 64
+            },
+            "type": "boolean"
+          },
           "owner": {
             "comment": {
               "markdownText": "The account/organization that is the project owner."
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 64
+              "lineNumber": 67
             },
             "type": "Account | Organization"
           },
@@ -2857,7 +2959,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 72
+              "lineNumber": 75
             },
             "type": "Account | undefined"
           },
@@ -2867,7 +2969,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 78
+              "lineNumber": 81
             },
             "type": "{\n    /** Preferred locale */\n    locale: string;\n  }"
           },
@@ -2877,7 +2979,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 84
+              "lineNumber": 87
             },
             "type": "Theme"
           }
@@ -2895,7 +2997,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 94
+              "lineNumber": 97
             },
             "type": "Partial<Record<string, ItemType>>"
           },
@@ -2905,7 +3007,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 101
+              "lineNumber": 104
             },
             "type": "Partial<Record<string, Field>>"
           },
@@ -2915,7 +3017,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 108
+              "lineNumber": 111
             },
             "type": "Partial<Record<string, Fieldset>>"
           },
@@ -2925,7 +3027,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 115
+              "lineNumber": 118
             },
             "type": "Partial<Record<string, User>>"
           },
@@ -2935,7 +3037,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 122
+              "lineNumber": 125
             },
             "type": "Partial<Record<string, SsoUser>>"
           }
@@ -2956,7 +3058,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 165
+              "lineNumber": 168
             },
             "type": "(itemTypeId: string) => Promise<Field[]>"
           },
@@ -2967,7 +3069,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 184
+              "lineNumber": 187
             },
             "type": "(itemTypeId: string) => Promise<Fieldset[]>"
           },
@@ -2978,7 +3080,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 201
+              "lineNumber": 204
             },
             "type": "() => Promise<Field[]>"
           },
@@ -2989,7 +3091,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 214
+              "lineNumber": 217
             },
             "type": "() => Promise<User[]>"
           },
@@ -3000,7 +3102,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 227
+              "lineNumber": 230
             },
             "type": "() => Promise<SsoUser[]>"
           }
@@ -3019,7 +3121,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 249
+              "lineNumber": 252
             },
             "type": "(params: Record<string, unknown>) => Promise<void>"
           },
@@ -3030,7 +3132,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 300
+              "lineNumber": 303
             },
             "type": "(\n    fieldId: string,\n    changes: FieldAppearanceChange[],\n  ) => Promise<void>"
           }
@@ -3049,7 +3151,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 405
+              "lineNumber": 408
             },
             "type": "(message: string) => Promise<void>"
           },
@@ -3060,7 +3162,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 420
+              "lineNumber": 423
             },
             "type": "(message: string) => Promise<void>"
           },
@@ -3071,7 +3173,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 444
+              "lineNumber": 447
             },
             "type": "<CtaValue = unknown>(\n    toast: Toast<CtaValue>,\n  ) => Promise<CtaValue | null>"
           }
@@ -3090,7 +3192,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 330
+              "lineNumber": 333
             },
             "type": "(itemTypeId: string) => Promise<Item | null>"
           },
@@ -3101,7 +3203,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 351
+              "lineNumber": 354
             },
             "type": "{\n    (\n      itemTypeId: string,\n      options: { multiple: true; initialLocationQuery?: ItemListLocationQuery },\n    ): Promise<Item[] | null>;\n    (\n      itemTypeId: string,\n      options?: {\n        multiple: false;\n        initialLocationQuery?: ItemListLocationQuery;\n      },\n    ): Promise<Item | null>;\n  }"
           },
@@ -3112,7 +3214,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 383
+              "lineNumber": 386
             },
             "type": "(itemId: string) => Promise<Item | null>"
           }
@@ -3131,7 +3233,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 471
+              "lineNumber": 474
             },
             "type": "{\n    (options: { multiple: true }): Promise<Upload[] | null>;\n    (options?: { multiple: false }): Promise<Upload | null>;\n  }"
           },
@@ -3142,7 +3244,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 499
+              "lineNumber": 502
             },
             "type": "(\n    uploadId: string,\n  ) => Promise<(Upload & { deleted?: true }) | null>"
           },
@@ -3153,7 +3255,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 527
+              "lineNumber": 530
             },
             "type": "(\n    /** The \"single asset\" field structure */\n    fileFieldValue: FileFieldValue,\n    /** Shows metadata information for a specific locale */\n    locale?: string,\n  ) => Promise<FileFieldValue | null>"
           }
@@ -3172,7 +3274,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 558
+              "lineNumber": 561
             },
             "type": "(modal: Modal) => Promise<unknown>"
           },
@@ -3183,7 +3285,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 595
+              "lineNumber": 598
             },
             "type": "(options: ConfirmOptions) => Promise<unknown>"
           }
@@ -3202,7 +3304,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 609
+              "lineNumber": 612
             },
             "type": "(path: string) => Promise<void>"
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datocms-plugin-sdk",
-  "version": "2.1.0-alpha.0",
+  "version": "2.1.0-alpha.1",
   "description": "DatoCMS Plugin SDK",
   "keywords": [
     "datocms",
@@ -36,7 +36,7 @@
     "url": "https://github.com/datocms/plugins-sdk/issues"
   },
   "dependencies": {
-    "@datocms/cma-client": "next",
+    "@datocms/cma-client": "^5.2.0-alpha.1",
     "@types/react": "^17.0.3",
     "datocms-structured-text-utils": "^2.0.0",
     "penpal": "^4.1.1"
@@ -45,5 +45,5 @@
     "glob": "^11.0.0",
     "typescript": "^5.6.2"
   },
-  "gitHead": "614ec540796d1d8065543bc6ff88da2f62764956"
+  "gitHead": "423f893f8f19b054ae769e2dff1787342f866fab"
 }

package/src/connect.ts

@@ -7,6 +7,7 @@ import type { CustomMarksForStructuredTextFieldHook } from './hooks/customMarksF
 import type { ExecuteFieldDropdownActionHook } from './hooks/executeFieldDropdownAction';
 import type { ExecuteItemFormDropdownActionHook } from './hooks/executeItemFormDropdownAction';
 import type { ExecuteItemsDropdownActionHook } from './hooks/executeItemsDropdownAction';
+import type { ExecuteSchemaItemTypeDropdownActionHook } from './hooks/executeSchemaItemTypeDropdownAction';
 import type { ExecuteUploadsDropdownActionHook } from './hooks/executeUploadsDropdownAction';
 import type { FieldDropdownActionsHook } from './hooks/fieldDropdownActions';
 import type { InitialLocationQueryForItemSelectorHook } from './hooks/initialLocationQueryForItemSelector';
@@ -66,6 +67,7 @@ import {
   RenderUploadSidebarPanelHook,
   renderUploadSidebarPanelBootstrapper,
 } from './hooks/renderUploadSidebarPanel';
+import type { SchemaItemTypeDropdownActionsHook } from './hooks/schemaItemTypeDropdownActions';
 import type { SettingsAreaSidebarItemGroupsHook } from './hooks/settingsAreaSidebarItemGroups';
 import { UploadSidebarPanelsHook } from './hooks/uploadSidebarPanels';
 import { UploadSidebarsHook } from './hooks/uploadSidebars';
@@ -87,6 +89,7 @@ export type FullConnectParameters = AssetSourcesHook &
   ExecuteFieldDropdownActionHook &
   ExecuteItemFormDropdownActionHook &
   ExecuteItemsDropdownActionHook &
+  ExecuteSchemaItemTypeDropdownActionHook &
   ExecuteUploadsDropdownActionHook &
   FieldDropdownActionsHook &
   InitialLocationQueryForItemSelectorHook &
@@ -116,6 +119,7 @@ export type FullConnectParameters = AssetSourcesHook &
   RenderPageHook &
   RenderUploadSidebarHook &
   RenderUploadSidebarPanelHook &
+  SchemaItemTypeDropdownActionsHook &
   SettingsAreaSidebarItemGroupsHook &
   UploadsDropdownActionsHook &
   UploadSidebarPanelsHook &

package/src/ctx/base.ts

@@ -60,6 +60,9 @@ type ProjectProperties = {
   /** The ID of the current environment */
   environment: string;
 
+  /** Whether the current environment is the primary one */
+  isEnvironmentPrimary: boolean;
+
   /** The account/organization that is the project owner */
   owner: Account | Organization;
 

package/src/hooks/executeSchemaItemTypeDropdownAction.ts

@@ -0,0 +1,24 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+
+type ItemType = SchemaTypes.ItemType;
+
+export type ExecuteSchemaItemTypeDropdownActionHook = {
+  /**
+   * Use this function to execute a particular dropdown action defined via
+   * the `schemaItemTypeDropdownActions()` hook.
+   *
+   * @tag dropdownActions
+   */
+  executeSchemaItemTypeDropdownAction: (
+    /** The ID of the action that was requested by the user */
+    actionId: string,
+    /** The model/block model on which the action should be executed */
+    itemType: ItemType,
+    ctx: ExecuteSchemaItemTypeDropdownActionCtx,
+  ) => Promise<void>;
+};
+
+export type ExecuteSchemaItemTypeDropdownActionCtx = Ctx<{
+  parameters: Record<string, unknown> | undefined;
+}>;

package/src/hooks/onBeforeItemUpsert.ts

@@ -7,8 +7,15 @@ type ItemCreateSchema = SchemaTypes.ItemCreateSchema;
 
 export type OnBeforeItemUpsertHook = {
   /**
-   * This function will be called before saving a new version of a record. You
-   * can stop the action by returning `false`
+   * This hook is called when the user attempts to save a record. You can use it to block record saving.
+   *
+   * If you return `false`, the record will NOT be saved. A small on-page error will say "A plugin blocked the action".
+   * However, for better UX, consider also using `ctx.alert()` to better explain to the user why their save was blocked.
+   *
+   * If you return `true`, the save will proceed as normal.
+   *
+   * This hook runs BEFORE serverside validation. You can use it to do your own additional validation before returning.
+   * Clientside validations are not affected by this hook, since those occur on individual fields' `onBlur()` events.
    *
    * @tag beforeHooks
    */
@@ -18,4 +25,25 @@ export type OnBeforeItemUpsertHook = {
   ) => MaybePromise<boolean>;
 };
 
-export type OnBeforeItemUpsertCtx = Ctx;
+export type OnBeforeItemUpsertCtx = Ctx<
+  {},
+  {
+    /**
+     * Smoothly navigates to a specific field in the form. If the field is
+     * localized it will switch language tab and then navigate to the chosen
+     * field.
+     *
+     * @example
+     *
+     * ```js
+     * const fieldPath = prompt(
+     *   'Please insert the path of a field in the form',
+     *   ctx.fieldPath,
+     * );
+     *
+     * await ctx.scrollToField(fieldPath);
+     * ```
+     */
+    scrollToField: (path: string, locale?: string) => Promise<void>;
+  }
+>;

package/src/hooks/renderPage.ts

@@ -17,6 +17,13 @@ export type RenderPageCtx = ImposedSizePluginFrameCtx<
   {
     /** The ID of the page that needs to be rendered */
     pageId: string;
+
+    /** Current page location */
+    location: {
+      pathname: string;
+      search: string;
+      hash: string;
+    };
   }
 >;
 

package/src/hooks/schemaItemTypeDropdownActions.ts

@@ -0,0 +1,22 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+import { DropdownAction, DropdownActionGroup } from '../shared';
+
+type ItemType = SchemaTypes.ItemType;
+
+export type SchemaItemTypeDropdownActionsHook = {
+  /**
+   * Use this function to define custom actions (or groups of actions) for a model/block model in the Schema section.
+   *
+   * The `executeSchemaItemTypeDropdownAction()` hook will be triggered once the user
+   * clicks on one of the defined actions.
+   *
+   * @tag dropdownActions
+   */
+  schemaItemTypeDropdownActions: (
+    itemType: ItemType,
+    ctx: SchemaItemTypeDropdownActionsCtx,
+  ) => Array<DropdownAction | DropdownActionGroup>;
+};
+
+export type SchemaItemTypeDropdownActionsCtx = Ctx;

package/src/icon.ts

@@ -1,8 +1,44 @@
 import { isRecord, isString } from './guardUtils.js';
 
-export type Icon =
-  | AwesomeFontIconIdentifier
-  | { type: 'svg'; viewBox: string; content: string };
+export type Icon = AwesomeFontIconIdentifier | SvgDefinition;
+
+/**
+ * Defines a custom SVG icon for use in DatoCMS plugins.
+ *
+ * To create an SVG definition from an existing SVG file:
+ * 1. Grab the `viewBox` attribute from your SVG element (e.g., "0 0 24 24")
+ * 2. Grab everything between the `<svg>` tags as the content (all the paths, circles, etc.)
+ *
+ * @example
+ * ```typescript
+ * // From this SVG:
+ * // <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+ * //   <path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/>
+ * // </svg>
+ *
+ * const starIcon: SvgDefinition = {
+ *   type: 'svg',
+ *   viewBox: '0 0 24 24',
+ *   content: '<path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/>'
+ * };
+ * ```
+ */
+export type SvgDefinition = {
+  /** Always set to 'svg' to indicate this is a custom SVG icon */
+  type: 'svg';
+
+  /**
+   * The viewBox attribute from your SVG element (e.g., "0 0 24 24").
+   * This defines the coordinate system and aspect ratio of the SVG.
+   */
+  viewBox: string;
+
+  /**
+   * The inner content of your SVG element — everything between the opening and closing <svg> tags.
+   * This includes all paths, circles, rectangles, and other SVG elements that make up your icon.
+   */
+  content: string;
+};
 
 export function isIcon(value: unknown): value is Icon {
   return (
@@ -14,6 +50,13 @@ export function isIcon(value: unknown): value is Icon {
   );
 }
 
+/**
+ * Font Awesome icon identifier for use in DatoCMS plugins.
+ *
+ * Use Font Awesome icons for consistent visual styling across the admin interface.
+ * This is the recommended approach for most plugin icons, with custom SVGs reserved
+ * primarily for brand/company logos where Font Awesome doesn't have an appropriate match.
+ */
 export type AwesomeFontIconIdentifier =
   | '0'
   | '00'

package/src/index.ts

@@ -25,6 +25,7 @@ export * from './hooks/customMarksForStructuredTextField';
 export * from './hooks/executeFieldDropdownAction';
 export * from './hooks/executeItemFormDropdownAction';
 export * from './hooks/executeItemsDropdownAction';
+export * from './hooks/executeSchemaItemTypeDropdownAction';
 export * from './hooks/executeUploadsDropdownAction';
 export * from './hooks/fieldDropdownActions';
 export * from './hooks/initialLocationQueryForItemSelector';
@@ -54,6 +55,7 @@ export * from './hooks/renderModal';
 export * from './hooks/renderPage';
 export * from './hooks/renderUploadSidebar';
 export * from './hooks/renderUploadSidebarPanel';
+export * from './hooks/schemaItemTypeDropdownActions';
 export * from './hooks/settingsAreaSidebarItemGroups';
 export * from './hooks/uploadsDropdownActions';
 export * from './hooks/uploadSidebarPanels';