datocms-plugin-sdk 2.0.0 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datocms-plugin-sdk",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "DatoCMS Plugin SDK",
   "keywords": [
     "datocms",
@@ -28,8 +28,8 @@
     "url": "git+https://github.com/datocms/plugins-sdk.git"
   },
   "scripts": {
-    "build": "npm run generate-doc && tsc && tsc --project ./tsconfig.esnext.json",
-    "generate-doc": "tsx generateDoc.ts && biome format --write src/manifest.ts",
+    "build": "npm run generate-manifest && tsc && tsc --project ./tsconfig.esnext.json",
+    "generate-manifest": "tsx generateManifest.ts && biome format --write src/manifest.ts",
     "prebuild": "rimraf dist"
   },
   "bugs": {
@@ -45,5 +45,5 @@
     "glob": "^11.0.0",
     "typescript": "^5.6.2"
   },
-  "gitHead": "8bf4ff5debe5b61f297e06def62ac00fb08bffb6"
+  "gitHead": "ba6263cc54345109ef3a4d4e60726e49888a70b2"
 }

package/src/ctx/base.ts

@@ -18,14 +18,15 @@ export type Ctx<
   AdditionalMethods extends Record<string, unknown> = Record<string, never>,
 > = BaseProperties & AdditionalProperties & BaseMethods & AdditionalMethods;
 
-/** Generic properties available in all the hooks */
-export type BaseProperties = {
-  /** The current DatoCMS project */
-  site: Site;
-  /** The ID of the current environment */
-  environment: string;
-  /** All the models of the current DatoCMS project, indexed by ID */
-  itemTypes: Partial<Record<string, ItemType>>;
+export type BaseProperties = PluginProperties &
+  AuthenticationProperties &
+  ProjectProperties &
+  EntityReposProperties;
+
+/**
+ * Information about the current user using the CMS
+ */
+type AuthenticationProperties = {
   /**
    * The current DatoCMS user. It can either be the owner or one of the
    * collaborators (regular or SSO).
@@ -38,8 +39,38 @@ export type BaseProperties = {
    * available if `currentUserAccessToken` additional permission is granted
    */
   currentUserAccessToken: string | undefined;
+};
+
+/**
+ * Information about the current plugin. Useful to access the plugin's global
+ * configuration object.
+ */
+type PluginProperties = {
   /** The current plugin */
   plugin: Plugin;
+};
+
+/*
+ * Information about the project
+ */
+type ProjectProperties = {
+  /** The current DatoCMS project */
+  site: Site;
+
+  /** The ID of the current environment */
+  environment: string;
+
+  /** The account that is the project owner */
+  owner: Account | Organization;
+
+  /**
+   * The account that is the project owner
+   *
+   * @deprecated Please use `.owner` instead, as the project owner can also be
+   *   an organization
+   */
+  account: Account | undefined;
+
   /**
    * UI preferences of the current user (right now, only the preferred locale is
    * available)
@@ -48,46 +79,47 @@ export type BaseProperties = {
     /** Preferred locale */
     locale: string;
   };
+
+  /** An object containing the theme colors for the current DatoCMS project */
+  theme: Theme;
+};
+
+/**
+ * These properties provide access to "entity repos", that is, the collection of
+ * resources of a particular type that have been loaded by the CMS up to this
+ * moment. The entity repos are objects, indexed by the ID of the entity itself.
+ */
+type EntityReposProperties = {
+  /** All the models of the current DatoCMS project, indexed by ID */
+  itemTypes: Partial<Record<string, ItemType>>;
+
   /**
    * All the fields currently loaded for the current DatoCMS project, indexed by
-   * ID. It will always contain the current model fields and all the fields of
-   * the blocks it might contain via Modular Content/Structured Text fields. If
-   * some fields you need are not present, use the `loadItemTypeFields` function
-   * to load them.
+   * ID. If some fields you need are not present, use the `loadItemTypeFields`
+   * function to load them.
    */
   fields: Partial<Record<string, Field>>;
+
   /**
    * All the fieldsets currently loaded for the current DatoCMS project, indexed
-   * by ID. It will always contain the current model fields and all the fields
-   * of the blocks it might contain via Modular Content/Structured Text fields.
-   * If some fields you need are not present, use the `loadItemTypeFieldsets`
-   * function to load them.
+   * by ID. If some fields you need are not present, use the
+   * `loadItemTypeFieldsets` function to load them.
    */
   fieldsets: Partial<Record<string, Fieldset>>;
-  /** An object containing the theme colors for the current DatoCMS project */
-  theme: Theme;
+
   /**
    * All the regular users currently loaded for the current DatoCMS project,
    * indexed by ID. It will always contain the current user. If some users you
    * need are not present, use the `loadUsers` function to load them.
    */
   users: Partial<Record<string, User>>;
+
   /**
    * All the SSO users currently loaded for the current DatoCMS project, indexed
    * by ID. It will always contain the current user. If some users you need are
    * not present, use the `loadSsoUsers` function to load them.
    */
   ssoUsers: Partial<Record<string, SsoUser>>;
-  /**
-   * The account that is the project owner
-   *
-   * @deprecated Please use `.owner` instead, as the project owner can also be
-   *   an organization
-   */
-  account: Account | undefined;
-  /** The account that is the project owner */
-  owner: Account | Organization;
-  /** The padding in px that must be applied to the body */
 };
 
 /** An object containing the theme colors for the current DatoCMS project */
@@ -100,7 +132,7 @@ export type Theme = {
 };
 
 export type BaseMethods = LoadDataMethods &
-  UpdateParametersMethods &
+  UpdatePluginParametersMethods &
   ToastMethods &
   ItemDialogMethods &
   UploadDialogMethods &
@@ -199,7 +231,7 @@ type LoadDataMethods = {
  * These methods can be used to update both plugin parameters and manual field
  * extensions configuration.
  */
-type UpdateParametersMethods = {
+type UpdatePluginParametersMethods = {
   /**
    * Updates the plugin parameters.
    *

package/src/ctx/commonExtras/field.ts

@@ -3,6 +3,10 @@ import type { SchemaTypes } from '@datocms/cma-client';
 type Field = SchemaTypes.Field;
 type ItemType = SchemaTypes.ItemType;
 
+/**
+ * These information describe the current state of the field where this plugin
+ * is applied to.
+ */
 export type FieldAdditionalProperties = {
   /** Whether the field is currently disabled or not */
   disabled: boolean;

package/src/ctx/commonExtras/itemForm.ts

@@ -25,19 +25,22 @@ export type ItemFormAdditionalProperties = {
   isSubmitting: boolean;
   /** Whether the form has some non-persisted changes or not */
   isFormDirty: boolean;
-  /** Current number of blocks present in form state */
-  blocksAnalysis: {
-    usage: {
-      /** Total number of blocks present in form state */
-      total: number;
-      /** Total number of blocks present in non-localized fields */
-      nonLocalized: number;
-      /** Total number of blocks present in localized fields, per locale */
-      perLocale: Record<string, number>;
-    };
-    /** Maximum number of blocks per item */
-    maximumPerItem: number;
+  /** Provides information on how many blocks are currently present in the form */
+  blocksAnalysis: BlocksAnalysis;
+};
+
+/** Current number of blocks present in form state */
+export type BlocksAnalysis = {
+  usage: {
+    /** Total number of blocks present in form state */
+    total: number;
+    /** Total number of blocks present in non-localized fields */
+    nonLocalized: number;
+    /** Total number of blocks present in localized fields, per locale */
+    perLocale: Record<string, number>;
   };
+  /** Maximum number of blocks per item */
+  maximumPerItem: number;
 };
 
 /**

package/src/ctx/commonExtras/sizing.ts

@@ -1,3 +1,4 @@
+/** A number of methods that you can use to control the size of the plugin frame */
 export type SizingUtilities = {
   /**
    * Listens for DOM changes and automatically calls `setHeight` when it detects

package/src/hooks/assetSources.ts

@@ -8,9 +8,11 @@ export type AssetSourcesHook = {
    *
    * @tag assetSources
    */
-  assetSources: (ctx: Ctx) => AssetSource[] | undefined;
+  assetSources: (ctx: AssetSourcesCtx) => AssetSource[] | undefined;
 };
 
+export type AssetSourcesCtx = Ctx;
+
 /** An additional asset source */
 export type AssetSource = {
   /**

package/src/hooks/buildItemPresentationInfo.ts

@@ -13,10 +13,12 @@ export type BuildItemPresentationInfoHook = {
    */
   buildItemPresentationInfo: (
     item: Item,
-    ctx: Ctx,
+    ctx: BuildItemPresentationInfoCtx,
   ) => MaybePromise<ItemPresentationInfo | undefined>;
 };
 
+export type BuildItemPresentationInfoCtx = Ctx;
+
 export type ItemPresentationInfo = {
   /** The title to present the record */
   title: string;

package/src/hooks/contentAreaSidebarItems.ts

@@ -7,9 +7,13 @@ export type ContentAreaSidebarItemsHook = {
    *
    * @tag sidebarItems
    */
-  contentAreaSidebarItems: (ctx: Ctx) => ContentAreaSidebarItem[];
+  contentAreaSidebarItems: (
+    ctx: ContentAreaSidebarItemsCtx,
+  ) => ContentAreaSidebarItem[];
 };
 
+export type ContentAreaSidebarItemsCtx = Ctx;
+
 export type ContentAreaSidebarItem = {
   /** Label to be shown. Must be unique. */
   label: string;

package/src/hooks/customBlockStylesForStructuredTextField.ts

@@ -14,11 +14,11 @@ export type CustomBlockStylesForStructuredTextFieldHook = {
    */
   customBlockStylesForStructuredTextField: (
     field: Field,
-    ctx: CustomBlockStylesForStructuredTextFieldHookCtx,
+    ctx: CustomBlockStylesForStructuredTextFieldCtx,
   ) => StructuredTextCustomBlockStyle[] | undefined;
 };
 
-export type CustomBlockStylesForStructuredTextFieldHookCtx = Ctx<{
+export type CustomBlockStylesForStructuredTextFieldCtx = Ctx<{
   itemType: ItemType;
 }>;
 

package/src/hooks/customMarksForStructuredTextField.ts

@@ -14,11 +14,11 @@ export type CustomMarksForStructuredTextFieldHook = {
    */
   customMarksForStructuredTextField: (
     field: Field,
-    ctx: CustomMarksForStructuredTextFieldHookCtx,
+    ctx: CustomMarksForStructuredTextFieldCtx,
   ) => StructuredTextCustomMark[] | undefined;
 };
 
-export type CustomMarksForStructuredTextFieldHookCtx = Ctx<{
+export type CustomMarksForStructuredTextFieldCtx = Ctx<{
   itemType: ItemType;
 }>;
 

package/src/hooks/executeFieldDropdownAction.ts

@@ -6,7 +6,14 @@ import type {
 } from '../ctx/commonExtras/itemForm';
 
 export type ExecuteFieldDropdownActionHook = {
+  /**
+   * Use this function to execute a particular dropdown action defined via
+   * the `fieldDropdownActions()` hook.
+   *
+   * @tag dropdownActions
+   */
   executeFieldDropdownAction: (
+    /** The ID of the action that was requested by the user */
     actionId: string,
     ctx: ExecuteFieldDropdownActionCtx,
   ) => Promise<void>;

package/src/hooks/executeItemFormDropdownAction.ts

@@ -5,7 +5,14 @@ import type {
 } from '../ctx/commonExtras/itemForm';
 
 export type ExecuteItemFormDropdownActionHook = {
+  /**
+   * Use this function to execute a particular dropdown action defined via
+   * the `itemFormDropdownActions()` hook.
+   *
+   * @tag dropdownActions
+   */
   executeItemFormDropdownAction: (
+    /** The ID of the action that was requested by the user */
     actionId: string,
     ctx: ExecuteItemFormDropdownActionCtx,
   ) => Promise<void>;

package/src/hooks/executeItemsDropdownAction.ts

@@ -4,8 +4,16 @@ import { Ctx } from '../ctx/base';
 type Item = SchemaTypes.Item;
 
 export type ExecuteItemsDropdownActionHook = {
+  /**
+   * Use this function to execute a particular dropdown action defined via
+   * the `itemsDropdownActions()` hook.
+   *
+   * @tag dropdownActions
+   */
   executeItemsDropdownAction: (
+    /** The ID of the action that was requested by the user */
     actionId: string,
+    /** The records on which the action should be executed */
     items: Item[],
     ctx: ExecuteItemsDropdownActionCtx,
   ) => Promise<void>;

package/src/hooks/executeUploadsDropdownAction.ts

@@ -4,12 +4,21 @@ import { Ctx } from '../ctx/base';
 type Upload = SchemaTypes.Upload;
 
 export type ExecuteUploadsDropdownActionHook = {
+  /**
+   * Use this function to execute a particular dropdown action defined via
+   * the `uploadsDropdownActions()` hook.
+   *
+   * @tag dropdownActions
+   */
   executeUploadsDropdownAction: (
+    /** The ID of the action that was requested by the user */
     actionId: string,
+    /** The assets on which the action should be executed */
     uploads: Upload[],
     ctx: ExecuteUploadsDropdownActionCtx,
   ) => Promise<void>;
 };
+
 export type ExecuteUploadsDropdownActionCtx = Ctx<{
   parameters: Record<string, unknown> | undefined;
 }>;

package/src/hooks/fieldDropdownActions.ts

@@ -7,6 +7,15 @@ import { DropdownAction, DropdownActionGroup } from '../shared';
 type Field = SchemaTypes.Field;
 
 export type FieldDropdownActionsHook = {
+  /**
+   * Use this function to define custom actions (or groups of actions) to be
+   * displayed at the individual field level in the record editing form.
+   *
+   * The `executeFieldDropdownAction()` hook will be triggered once the user
+   * clicks on one of the defined actions.
+   *
+   * @tag dropdownActions
+   */
   fieldDropdownActions: (
     field: Field,
     ctx: FieldDropdownActionsCtx,

package/src/hooks/initialLocationQueryForItemSelector.ts

@@ -16,10 +16,12 @@ export type InitialLocationQueryForItemSelectorHook = {
   initialLocationQueryForItemSelector: (
     openerField: Field,
     itemType: ItemType,
-    ctx: Ctx,
+    ctx: InitialLocationQueryForItemSelectorCtx,
   ) => MaybePromise<InitialLocationQueryForItemSelector | undefined>;
 };
 
+export type InitialLocationQueryForItemSelectorCtx = Ctx;
+
 export type InitialLocationQueryForItemSelector = {
   locationQuery: ItemListLocationQuery;
   /**

package/src/hooks/itemCollectionOutlets.ts

@@ -4,12 +4,20 @@ import { Ctx } from '../ctx/base';
 type ItemType = SchemaTypes.ItemType;
 
 export type ItemCollectionOutletsHook = {
+  /**
+   * Use this function to declare custom outlets to be shown at the top of a
+   * collection of records of a particular model
+   *
+   * @tag outlets
+   */
   itemCollectionOutlets: (
     itemType: ItemType,
-    ctx: Ctx,
+    ctx: ItemCollectionOutletsCtx,
   ) => ItemCollectionOutlet[];
 };
 
+export type ItemCollectionOutletsCtx = Ctx;
+
 /** An outlet to be shown at the top of a record's collection page */
 export type ItemCollectionOutlet = {
   /**

package/src/hooks/itemFormDropdownActions.ts

@@ -6,6 +6,15 @@ import { DropdownAction, DropdownActionGroup } from '../shared';
 type ItemType = SchemaTypes.ItemType;
 
 export type ItemFormDropdownActionsHook = {
+  /**
+   * Use this function to define custom actions (or groups of actions) to be
+   * displayed at when editing a particular record.
+   *
+   * The `executeItemFormDropdownAction()` hook will be triggered once the user
+   * clicks on one of the defined actions.
+   *
+   * @tag dropdownActions
+   */
   itemFormDropdownActions: (
     itemType: ItemType,
     ctx: ItemFormDropdownActionsCtx,

package/src/hooks/itemFormOutlets.ts

@@ -8,11 +8,16 @@ export type ItemFormOutletsHook = {
    * Use this function to declare custom outlets to be shown at the top of the
    * record's editing page
    *
-   * @tag itemFormOutlets
+   * @tag outlets
    */
-  itemFormOutlets: (itemType: ItemType, ctx: Ctx) => ItemFormOutlet[];
+  itemFormOutlets: (
+    itemType: ItemType,
+    ctx: ItemFormOutletsCtx,
+  ) => ItemFormOutlet[];
 };
 
+export type ItemFormOutletsCtx = Ctx;
+
 export type ItemFormOutlet = {
   /**
    * ID of the outlet. Will be the first argument for the `renderItemFormOutlet`

package/src/hooks/itemFormSidebarPanels.ts

@@ -13,10 +13,12 @@ export type ItemFormSidebarPanelsHook = {
    */
   itemFormSidebarPanels: (
     itemType: ItemType,
-    ctx: Ctx,
+    ctx: ItemFormSidebarPanelsCtx,
   ) => ItemFormSidebarPanel[];
 };
 
+export type ItemFormSidebarPanelsCtx = Ctx;
+
 export type ItemFormSidebarPanel = {
   /**
    * ID of the panel. Will be the first argument for the

package/src/hooks/itemFormSidebars.ts

@@ -10,9 +10,14 @@ export type ItemFormSidebarsHook = {
    *
    * @tag sidebarPanels
    */
-  itemFormSidebars: (itemType: ItemType, ctx: Ctx) => ItemFormSidebar[];
+  itemFormSidebars: (
+    itemType: ItemType,
+    ctx: ItemFormSidebarsCtx,
+  ) => ItemFormSidebar[];
 };
 
+export type ItemFormSidebarsCtx = Ctx;
+
 export type ItemFormSidebar = {
   /**
    * ID of the sidebar. Will be the first argument for the

package/src/hooks/itemsDropdownActions.ts

@@ -5,6 +5,18 @@ import { DropdownAction, DropdownActionGroup } from '../shared';
 type ItemType = SchemaTypes.ItemType;
 
 export type ItemsDropdownActionsHook = {
+  /**
+   * This function lets you set up custom actions (or groups of actions) that
+   * show up when the user:
+   *
+   * * selects multiple records in the collection view for batch operations, or
+   * * starts editing a specific record.
+   *
+   * The `executeItemsDropdownAction()` hook will be triggered once the user
+   * clicks on one of the defined actions.
+   *
+   * @tag dropdownActions
+   */
   itemsDropdownActions: (
     itemType: ItemType,
     ctx: ItemDropdownActionsCtx,

package/src/hooks/mainNavigationTabs.ts

@@ -8,9 +8,11 @@ export type MainNavigationTabsHook = {
    *
    * @tag pages
    */
-  mainNavigationTabs: (ctx: Ctx) => MainNavigationTab[];
+  mainNavigationTabs: (ctx: MainNavigationTabsCtx) => MainNavigationTab[];
 };
 
+export type MainNavigationTabsCtx = Ctx;
+
 /** A tab to be displayed in the top-bar of the UI */
 export type MainNavigationTab = {
   /** Label to be shown. Must be unique. */

package/src/hooks/manualFieldExtensions.ts

@@ -7,9 +7,13 @@ export type ManualFieldExtensionsHook = {
    *
    * @tag manualFieldExtensions
    */
-  manualFieldExtensions: (ctx: Ctx) => ManualFieldExtension[];
+  manualFieldExtensions: (
+    ctx: ManualFieldExtensionsCtx,
+  ) => ManualFieldExtension[];
 };
 
+export type ManualFieldExtensionsCtx = Ctx;
+
 export type ManualFieldExtension = {
   /**
    * ID of field extension. Will be the first argument for the

package/src/hooks/onBeforeItemUpsert.ts

@@ -14,6 +14,8 @@ export type OnBeforeItemUpsertHook = {
    */
   onBeforeItemUpsert: (
     createOrUpdateItemPayload: ItemUpdateSchema | ItemCreateSchema,
-    ctx: Ctx,
+    ctx: OnBeforeItemUpsertCtx,
   ) => MaybePromise<boolean>;
 };
+
+export type OnBeforeItemUpsertCtx = Ctx;

package/src/hooks/onBeforeItemsDestroy.ts

@@ -11,5 +11,10 @@ export type OnBeforeItemsDestroyHook = {
    *
    * @tag beforeHooks
    */
-  onBeforeItemsDestroy: (items: Item[], ctx: Ctx) => MaybePromise<boolean>;
+  onBeforeItemsDestroy: (
+    items: Item[],
+    ctx: OnBeforeItemsDestroyCtx,
+  ) => MaybePromise<boolean>;
 };
+
+export type OnBeforeItemsDestroyCtx = Ctx;

package/src/hooks/onBeforeItemsPublish.ts

@@ -11,5 +11,10 @@ export type OnBeforeItemsPublishHook = {
    *
    * @tag beforeHooks
    */
-  onBeforeItemsPublish: (items: Item[], ctx: Ctx) => MaybePromise<boolean>;
+  onBeforeItemsPublish: (
+    items: Item[],
+    ctx: OnBeforeItemsPublishCtx,
+  ) => MaybePromise<boolean>;
 };
+
+export type OnBeforeItemsPublishCtx = Ctx;

package/src/hooks/onBeforeItemsUnpublish.ts

@@ -11,5 +11,10 @@ export type OnBeforeItemsUnpublishHook = {
    *
    * @tag beforeHooks
    */
-  onBeforeItemsUnpublish: (items: Item[], ctx: Ctx) => MaybePromise<boolean>;
+  onBeforeItemsUnpublish: (
+    items: Item[],
+    ctx: OnBeforeItemsUnpublishCtx,
+  ) => MaybePromise<boolean>;
 };
+
+export type OnBeforeItemsUnpublishCtx = Ctx;

package/src/hooks/overrideFieldExtensions.ts

@@ -14,11 +14,11 @@ export type OverrideFieldExtensionsHook = {
    */
   overrideFieldExtensions: (
     field: Field,
-    ctx: OverrideFieldExtensionsHookCtx,
+    ctx: OverrideFieldExtensionsCtx,
   ) => FieldExtensionOverride | undefined;
 };
 
-export type OverrideFieldExtensionsHookCtx = Ctx<{
+export type OverrideFieldExtensionsCtx = Ctx<{
   itemType: ItemType;
 }>;
 

package/src/hooks/renderItemCollectionOutlet.ts

@@ -2,6 +2,12 @@ import { SelfResizingPluginFrameCtx } from '../ctx/pluginFrame';
 import { containedRenderModeBootstrapper } from '../utils';
 
 export type RenderItemCollectionOutletHook = {
+  /**
+   * This function will be called when the plugin needs to render an outlet
+   * defined by the `itemFormOutlets()` hook.
+   *
+   * @tag outlets
+   */
   renderItemCollectionOutlet: (
     itemCollectionOutletId: string,
     ctx: RenderItemCollectionOutletCtx,

package/src/hooks/renderItemFormOutlet.ts

@@ -7,10 +7,10 @@ import { containedRenderModeBootstrapper } from '../utils';
 
 export type RenderItemFormOutletHook = {
   /**
-   * This function will be called when the plugin needs to render an outlet (see
-   * the `itemFormOutlets` function)
+   * This function will be called when the plugin needs to render an outlet
+   * defined by the `itemFormOutlets()` hook.
    *
-   * @tag itemFormOutlets
+   * @tag outlets
    */
   renderItemFormOutlet: (
     itemFormOutletId: string,

package/src/hooks/settingsAreaSidebarItemGroups.ts

@@ -8,9 +8,13 @@ export type SettingsAreaSidebarItemGroupsHook = {
    *
    * @tag pages
    */
-  settingsAreaSidebarItemGroups: (ctx: Ctx) => SettingsAreaSidebarItemGroup[];
+  settingsAreaSidebarItemGroups: (
+    ctx: SettingsAreaSidebarItemGroupsCtx,
+  ) => SettingsAreaSidebarItemGroup[];
 };
 
+export type SettingsAreaSidebarItemGroupsCtx = Ctx;
+
 /**
  * The sidebar in the Settings Area presents a number of pages grouped by topic.
  * This object represents a new group to be added in the sideebar to the