datocms-plugin-sdk 2.0.13 → 2.0.15

package/manifest.json

@@ -1616,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": [
@@ -1642,7 +1642,7 @@
                 },
                 "location": {
                   "filePath": "src/hooks/onBeforeItemUpsert.ts",
-                  "lineNumber": 40
+                  "lineNumber": 47
                 },
                 "type": "(path: string, locale?: string) => Promise<void>"
               }
@@ -1653,7 +1653,7 @@
       "returnType": "MaybePromise<boolean>",
       "location": {
         "filePath": "src/hooks/onBeforeItemUpsert.ts",
-        "lineNumber": 15
+        "lineNumber": 22
       }
     },
     "manualFieldExtensions": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datocms-plugin-sdk",
-  "version": "2.0.13",
+  "version": "2.0.15",
   "description": "DatoCMS Plugin SDK",
   "keywords": [
     "datocms",
@@ -45,5 +45,5 @@
     "glob": "^11.0.0",
     "typescript": "^5.6.2"
   },
-  "gitHead": "1420d4ce991da7c84da85b1b4e1375df19e156d7"
+  "gitHead": "6698d6f38549b0487ee4721862483d811512bf73"
 }

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
    */

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/manifest.ts

@@ -1745,7 +1745,7 @@ export const manifest: Manifest = {
       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`.',
+          '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: [
@@ -1773,7 +1773,7 @@ export const manifest: Manifest = {
                 },
                 location: {
                   filePath: 'src/hooks/onBeforeItemUpsert.ts',
-                  lineNumber: 40,
+                  lineNumber: 47,
                 },
                 type: '(path: string, locale?: string) => Promise<void>',
               },
@@ -1784,7 +1784,7 @@ export const manifest: Manifest = {
       returnType: 'MaybePromise<boolean>',
       location: {
         filePath: 'src/hooks/onBeforeItemUpsert.ts',
-        lineNumber: 15,
+        lineNumber: 22,
       },
     },
     manualFieldExtensions: {