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

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    }"
               }
             }
           }
@@ -1106,6 +1139,140 @@
         "lineNumber": 14
       }
     },
+    "renderInspectorPanel": {
+      "name": "renderInspectorPanel",
+      "comment": {
+        "markdownText": "This function will be called when an inspector needs to render a specific\npanel (see the `renderInspector` and `setInspectorMode` functions).",
+        "tag": "inspector"
+      },
+      "nonCtxArguments": [
+        {
+          "name": "panelId",
+          "typeName": "string"
+        }
+      ],
+      "ctxArgument": {
+        "type": "ImposedSizePluginFrameCtx",
+        "additionalProperties": [
+          {
+            "items": {
+              "panelId": {
+                "comment": {
+                  "markdownText": "The ID of the inspector panel that needs to be rendered."
+                },
+                "location": {
+                  "filePath": "src/hooks/renderInspectorPanel.ts",
+                  "lineNumber": 18
+                },
+                "type": "string"
+              },
+              "parameters": {
+                "comment": {
+                  "markdownText": "The arbitrary `parameters` of the modal declared in the `setInspectorMode`\nfunction."
+                },
+                "location": {
+                  "filePath": "src/hooks/renderInspectorPanel.ts",
+                  "lineNumber": 24
+                },
+                "type": "Record<string, unknown>"
+              }
+            }
+          }
+        ],
+        "additionalMethods": []
+      },
+      "returnType": "void",
+      "location": {
+        "filePath": "src/hooks/renderInspectorPanel.ts",
+        "lineNumber": 11
+      }
+    },
+    "renderInspector": {
+      "name": "renderInspector",
+      "comment": {
+        "markdownText": "This function will be called when the plugin needs to render a specific\ninspector. Inspectors provide a side panel interface for displaying and\ninteracting with content alongside a custom interface.",
+        "tag": "inspector",
+        "example": "connect({\n  renderInspector(inspectorId, ctx) {\n    render(\n      <div>\n        <h1>Inspector: {inspectorId}</h1>\n        <button onClick={() => ctx.setInspectorMode({\n          type: 'itemEditor',\n          itemId: 'some-item-id'\n        })}>\n          Show Item Editor\n        </button>\n      </div>\n    );\n  }\n});"
+      },
+      "nonCtxArguments": [
+        {
+          "name": "inspectorId",
+          "typeName": "string"
+        }
+      ],
+      "ctxArgument": {
+        "type": "ImposedSizePluginFrameCtx",
+        "additionalProperties": [
+          {
+            "items": {
+              "inspectorId": {
+                "comment": {
+                  "markdownText": "The ID of the inspector that needs to be rendered."
+                },
+                "location": {
+                  "filePath": "src/hooks/renderInspector.ts",
+                  "lineNumber": 80
+                },
+                "type": "string"
+              },
+              "highlightedItemId": {
+                "comment": {
+                  "markdownText": "The ID of the record the currently is highlighted by the user."
+                },
+                "location": {
+                  "filePath": "src/hooks/renderInspector.ts",
+                  "lineNumber": 83
+                },
+                "type": "string | undefined"
+              },
+              "location": {
+                "comment": {
+                  "markdownText": "Current page location."
+                },
+                "location": {
+                  "filePath": "src/hooks/renderInspector.ts",
+                  "lineNumber": 86
+                },
+                "type": "{\n      pathname: string;\n      search: string;\n      hash: string;\n    }"
+              }
+            }
+          }
+        ],
+        "additionalMethods": [
+          {
+            "items": {
+              "setInspectorMode": {
+                "comment": {
+                  "markdownText": "Changes the current display mode of the inspector. This allows the plugin\nto dynamically switch between showing a record list, record editor, or custom\npanel within the inspector interface.",
+                  "example": "// Switch to record editor mode\nawait ctx.setInspectorMode({\n  type: 'itemEditor',\n  itemId: 'item-123',\n  fieldPath: 'title'\n});\n\n// Switch to record list mode\nawait ctx.setInspectorMode({ type: 'itemList' });\nawait ctx.setInspectorItemListData({\n  title: 'Related Records',\n  itemIds: ['item-1', 'item-2', 'item-3']\n});\n\n// Switch to custom panel mode\nawait ctx.setInspectorMode({\n  type: 'customPanel',\n  panelId: 'my-custom-panel',\n  parameters: { filter: 'active' }\n});\n\n// Low intent mode change - won't interrupt editing with unsaved changes\nawait ctx.setInspectorMode(\n  { type: 'itemList' },\n  { ignoreIfUnsavedChanges: true }\n);"
+                },
+                "location": {
+                  "filePath": "src/hooks/renderInspector.ts",
+                  "lineNumber": 136
+                },
+                "type": "(\n      mode: InspectorMode,\n      options?: SetInspectorModeOptions,\n    ) => Promise<void>"
+              },
+              "setInspectorItemListData": {
+                "comment": {
+                  "markdownText": "Sets the data for the item list inspector mode.",
+                  "example": "// Set the item list data\nawait ctx.setInspectorItemListData({\n  title: 'Related Records',\n  itemIds: ['item-1', 'item-2', 'item-3']\n});\n\n// Switch to item list mode\nawait ctx.setInspectorMode({ type: 'itemList' });"
+                },
+                "location": {
+                  "filePath": "src/hooks/renderInspector.ts",
+                  "lineNumber": 157
+                },
+                "type": "(data: {\n      /** The title to show in the inspector header */\n      title: string;\n      /** Array of record IDs to display in the list */\n      itemIds: string[];\n    }) => Promise<void>"
+              }
+            }
+          }
+        ]
+      },
+      "returnType": "void",
+      "location": {
+        "filePath": "src/hooks/renderInspector.ts",
+        "lineNumber": 73
+      }
+    },
     "renderFieldExtension": {
       "name": "renderFieldExtension",
       "comment": {
@@ -1583,7 +1750,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 +1761,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 +2301,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 +3066,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 +3093,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 72
+              "lineNumber": 75
             },
             "type": "Account | undefined"
           },
@@ -2867,7 +3103,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 78
+              "lineNumber": 81
             },
             "type": "{\n    /** Preferred locale */\n    locale: string;\n  }"
           },
@@ -2877,7 +3113,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 84
+              "lineNumber": 87
             },
             "type": "Theme"
           }
@@ -2895,7 +3131,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 94
+              "lineNumber": 97
             },
             "type": "Partial<Record<string, ItemType>>"
           },
@@ -2905,7 +3141,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 101
+              "lineNumber": 104
             },
             "type": "Partial<Record<string, Field>>"
           },
@@ -2915,7 +3151,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 108
+              "lineNumber": 111
             },
             "type": "Partial<Record<string, Fieldset>>"
           },
@@ -2925,7 +3161,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 115
+              "lineNumber": 118
             },
             "type": "Partial<Record<string, User>>"
           },
@@ -2935,7 +3171,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 122
+              "lineNumber": 125
             },
             "type": "Partial<Record<string, SsoUser>>"
           }
@@ -2956,7 +3192,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 165
+              "lineNumber": 168
             },
             "type": "(itemTypeId: string) => Promise<Field[]>"
           },
@@ -2967,7 +3203,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 184
+              "lineNumber": 187
             },
             "type": "(itemTypeId: string) => Promise<Fieldset[]>"
           },
@@ -2978,7 +3214,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 201
+              "lineNumber": 204
             },
             "type": "() => Promise<Field[]>"
           },
@@ -2989,7 +3225,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 214
+              "lineNumber": 217
             },
             "type": "() => Promise<User[]>"
           },
@@ -3000,7 +3236,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 227
+              "lineNumber": 230
             },
             "type": "() => Promise<SsoUser[]>"
           }
@@ -3019,7 +3255,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 249
+              "lineNumber": 252
             },
             "type": "(params: Record<string, unknown>) => Promise<void>"
           },
@@ -3030,7 +3266,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 300
+              "lineNumber": 303
             },
             "type": "(\n    fieldId: string,\n    changes: FieldAppearanceChange[],\n  ) => Promise<void>"
           }
@@ -3049,7 +3285,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 405
+              "lineNumber": 408
             },
             "type": "(message: string) => Promise<void>"
           },
@@ -3060,7 +3296,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 420
+              "lineNumber": 423
             },
             "type": "(message: string) => Promise<void>"
           },
@@ -3071,7 +3307,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 444
+              "lineNumber": 447
             },
             "type": "<CtaValue = unknown>(\n    toast: Toast<CtaValue>,\n  ) => Promise<CtaValue | null>"
           }
@@ -3090,7 +3326,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 330
+              "lineNumber": 333
             },
             "type": "(itemTypeId: string) => Promise<Item | null>"
           },
@@ -3101,7 +3337,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 +3348,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 383
+              "lineNumber": 386
             },
             "type": "(itemId: string) => Promise<Item | null>"
           }
@@ -3131,7 +3367,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 +3378,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 499
+              "lineNumber": 502
             },
             "type": "(\n    uploadId: string,\n  ) => Promise<(Upload & { deleted?: true }) | null>"
           },
@@ -3153,7 +3389,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 +3408,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 558
+              "lineNumber": 561
             },
             "type": "(modal: Modal) => Promise<unknown>"
           },
@@ -3183,7 +3419,7 @@
             },
             "location": {
               "filePath": "src/ctx/base.ts",
-              "lineNumber": 595
+              "lineNumber": 598
             },
             "type": "(options: ConfirmOptions) => Promise<unknown>"
           }
@@ -3202,7 +3438,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.2",
   "description": "DatoCMS Plugin SDK",
   "keywords": [
     "datocms",
@@ -36,14 +36,15 @@
     "url": "https://github.com/datocms/plugins-sdk/issues"
   },
   "dependencies": {
-    "@datocms/cma-client": "next",
+    "@datocms/cma-client": "^5.2.2",
     "@types/react": "^17.0.3",
     "datocms-structured-text-utils": "^2.0.0",
+    "emoji-regex-xs": "*",
     "penpal": "^4.1.1"
   },
   "devDependencies": {
     "glob": "^11.0.0",
     "typescript": "^5.6.2"
   },
-  "gitHead": "614ec540796d1d8065543bc6ff88da2f62764956"
+  "gitHead": "774ac774ad3125a0ee778b691a660d651cd67f29"
 }

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';
@@ -36,6 +37,14 @@ import {
   RenderFieldExtensionHook,
   renderFieldExtensionBootstrapper,
 } from './hooks/renderFieldExtension';
+import {
+  RenderInspectorHook,
+  renderInspectorBootstrapper,
+} from './hooks/renderInspector';
+import {
+  RenderInspectorPanelHook,
+  renderInspectorPanelBootstrapper,
+} from './hooks/renderInspectorPanel';
 import {
   RenderItemCollectionOutletHook,
   renderItemCollectionOutletBootstrapper,
@@ -66,6 +75,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 +97,7 @@ export type FullConnectParameters = AssetSourcesHook &
   ExecuteFieldDropdownActionHook &
   ExecuteItemFormDropdownActionHook &
   ExecuteItemsDropdownActionHook &
+  ExecuteSchemaItemTypeDropdownActionHook &
   ExecuteUploadsDropdownActionHook &
   FieldDropdownActionsHook &
   InitialLocationQueryForItemSelectorHook &
@@ -114,8 +125,11 @@ export type FullConnectParameters = AssetSourcesHook &
   RenderManualFieldExtensionConfigScreenHook &
   RenderModalHook &
   RenderPageHook &
+  RenderInspectorHook &
+  RenderInspectorPanelHook &
   RenderUploadSidebarHook &
   RenderUploadSidebarPanelHook &
+  SchemaItemTypeDropdownActionsHook &
   SettingsAreaSidebarItemGroupsHook &
   UploadsDropdownActionsHook &
   UploadSidebarPanelsHook &
@@ -260,6 +274,8 @@ export async function connect(
       renderManualFieldExtensionConfigScreenBootstrapper,
     renderModal: renderModalBootstrapper,
     renderPage: renderPageBootstrapper,
+    renderInspector: renderInspectorBootstrapper,
+    renderInspectorPanel: renderInspectorPanelBootstrapper,
     renderUploadSidebar: renderUploadSidebarBootstrapper,
     renderUploadSidebarPanel: renderUploadSidebarPanelBootstrapper,
   };

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

@@ -1,3 +1,7 @@
+import emojiRegex from 'emoji-regex-xs';
+
+export type Emoji = string & { readonly __brand: 'Emoji' };
+
 export function isNullish(value: unknown): value is null | undefined {
   return value === null || value === undefined;
 }
@@ -10,6 +14,15 @@ export function isString(value: unknown): value is string {
   return typeof value === 'string';
 }
 
+export function isEmoji(value: unknown): value is Emoji {
+  if (!isString(value)) return false;
+
+  const regex = emojiRegex();
+  const match = value.match(regex);
+
+  return match !== null && match.length === 1 && match[0] === value;
+}
+
 export function isNumber(value: unknown): value is number {
   return typeof value === 'number';
 }

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