datocms-plugin-sdk 2.0.0 → 2.0.2

package/dist/types/hooks/executeFieldDropdownAction.d.ts

@@ -2,7 +2,15 @@ import { Ctx } from '../ctx/base';
 import type { FieldAdditionalProperties } from '../ctx/commonExtras/field';
 import type { ItemFormAdditionalMethods, ItemFormAdditionalProperties } from '../ctx/commonExtras/itemForm';
 export type ExecuteFieldDropdownActionHook = {
-    executeFieldDropdownAction: (actionId: string, ctx: ExecuteFieldDropdownActionCtx) => Promise<void>;
+    /**
+     * 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>;
 };
 export type ExecuteFieldDropdownActionCtx = Ctx<ItemFormAdditionalProperties & FieldAdditionalProperties & {
     parameters: Record<string, unknown> | undefined;

package/dist/types/hooks/executeItemFormDropdownAction.d.ts

@@ -1,7 +1,15 @@
 import { Ctx } from '../ctx/base';
 import type { ItemFormAdditionalMethods, ItemFormAdditionalProperties } from '../ctx/commonExtras/itemForm';
 export type ExecuteItemFormDropdownActionHook = {
-    executeItemFormDropdownAction: (actionId: string, ctx: ExecuteItemFormDropdownActionCtx) => Promise<void>;
+    /**
+     * 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>;
 };
 export type ExecuteItemFormDropdownActionCtx = Ctx<ItemFormAdditionalProperties & {
     parameters: Record<string, unknown> | undefined;

package/dist/types/hooks/executeItemsDropdownAction.d.ts

@@ -2,7 +2,17 @@ import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
 type Item = SchemaTypes.Item;
 export type ExecuteItemsDropdownActionHook = {
-    executeItemsDropdownAction: (actionId: string, items: Item[], ctx: ExecuteItemsDropdownActionCtx) => Promise<void>;
+    /**
+     * 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>;
 };
 export type ExecuteItemsDropdownActionCtx = Ctx<{
     parameters: Record<string, unknown> | undefined;

package/dist/types/hooks/executeUploadsDropdownAction.d.ts

@@ -2,7 +2,17 @@ import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
 type Upload = SchemaTypes.Upload;
 export type ExecuteUploadsDropdownActionHook = {
-    executeUploadsDropdownAction: (actionId: string, uploads: Upload[], ctx: ExecuteUploadsDropdownActionCtx) => Promise<void>;
+    /**
+     * 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/dist/types/hooks/fieldDropdownActions.d.ts

@@ -5,6 +5,15 @@ import { ItemFormAdditionalProperties } from '../ctx/commonExtras/itemForm';
 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) => Array<DropdownAction | DropdownActionGroup>;
 };
 export type FieldDropdownActionsCtx = Ctx<ItemFormAdditionalProperties & FieldAdditionalProperties>;

package/dist/types/hooks/initialLocationQueryForItemSelector.d.ts

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

package/dist/types/hooks/itemCollectionOutlets.d.ts

@@ -2,8 +2,15 @@ import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
 type ItemType = SchemaTypes.ItemType;
 export type ItemCollectionOutletsHook = {
-    itemCollectionOutlets: (itemType: ItemType, ctx: Ctx) => ItemCollectionOutlet[];
+    /**
+     * 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: ItemCollectionOutletsCtx) => ItemCollectionOutlet[];
 };
+export type ItemCollectionOutletsCtx = Ctx;
 /** An outlet to be shown at the top of a record's collection page */
 export type ItemCollectionOutlet = {
     /**

package/dist/types/hooks/itemFormDropdownActions.d.ts

@@ -4,6 +4,15 @@ import { ItemFormAdditionalProperties } from '../ctx/commonExtras/itemForm';
 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) => Array<DropdownAction | DropdownActionGroup>;
 };
 export type ItemFormDropdownActionsCtx = ItemFormDropdownActionsProperties;

package/dist/types/hooks/itemFormOutlets.d.ts

@@ -6,10 +6,11 @@ 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/dist/types/hooks/itemFormSidebarPanels.d.ts

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

package/dist/types/hooks/itemFormSidebars.d.ts

@@ -8,8 +8,9 @@ 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/dist/types/hooks/itemsDropdownActions.d.ts

@@ -3,6 +3,18 @@ import { Ctx } from '../ctx/base';
 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) => Array<DropdownAction | DropdownActionGroup>;
 };
 export type ItemDropdownActionsCtx = Ctx<{

package/dist/types/hooks/mainNavigationTabs.d.ts

@@ -7,8 +7,9 @@ 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/dist/types/hooks/manualFieldExtensions.d.ts

@@ -6,8 +6,9 @@ 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/dist/types/hooks/onBeforeItemUpsert.d.ts

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

package/dist/types/hooks/onBeforeItemsDestroy.d.ts

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

package/dist/types/hooks/onBeforeItemsPublish.d.ts

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

package/dist/types/hooks/onBeforeItemsUnpublish.d.ts

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

package/dist/types/hooks/overrideFieldExtensions.d.ts

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

package/dist/types/hooks/renderItemCollectionOutlet.d.ts

@@ -1,5 +1,11 @@
 import { SelfResizingPluginFrameCtx } from '../ctx/pluginFrame';
 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) => void;
 };
 export type RenderItemCollectionOutletCtx = SelfResizingPluginFrameCtx<'renderItemCollectionOutlet', {

package/dist/types/hooks/renderItemFormOutlet.d.ts

@@ -2,10 +2,10 @@ import { ItemFormAdditionalMethods, ItemFormAdditionalProperties } from '../ctx/
 import { SelfResizingPluginFrameCtx } from '../ctx/pluginFrame';
 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, ctx: RenderItemFormOutletCtx) => void;
 };

package/dist/types/hooks/settingsAreaSidebarItemGroups.d.ts

@@ -7,8 +7,9 @@ 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

package/dist/types/hooks/uploadSidebarPanels.d.ts

@@ -6,8 +6,9 @@ export type UploadSidebarPanelsHook = {
      *
      * @tag sidebarPanels
      */
-    uploadSidebarPanels: (ctx: Ctx) => UploadSidebarPanel[];
+    uploadSidebarPanels: (ctx: UploadSidebarPanelsCtx) => UploadSidebarPanel[];
 };
+export type UploadSidebarPanelsCtx = Ctx;
 export type UploadSidebarPanel = {
     /**
      * ID of the panel. Will be the first argument for the

package/dist/types/hooks/uploadSidebars.d.ts

@@ -6,8 +6,9 @@ export type UploadSidebarsHook = {
      *
      * @tag sidebarPanels
      */
-    uploadSidebars: (ctx: Ctx) => UploadSidebar[];
+    uploadSidebars: (ctx: UploadSidebarsCtx) => UploadSidebar[];
 };
+export type UploadSidebarsCtx = Ctx;
 export type UploadSidebar = {
     /**
      * ID of the sidebar. Will be the first argument for the

package/dist/types/hooks/uploadsDropdownActions.d.ts

@@ -1,5 +1,19 @@
 import { Ctx } from '../ctx/base';
 import { DropdownAction, DropdownActionGroup } from '../shared';
 export type UploadsDropdownActionsHook = {
-    uploadsDropdownActions: (ctx: Ctx) => Array<DropdownAction | DropdownActionGroup>;
+    /**
+     * This function lets you set up custom actions (or groups of actions) that
+     * show up when the user:
+     *
+     * * selects multiple assets in the Media Area for batch operations, or
+     * * opens up a specific asset from the Media Area.
+     *
+     * The `executeUploadsDropdownAction()` hook will be triggered once the user
+     * clicks on one of the defined actions.
+     *
+     * @tag dropdownActions
+     */
+    uploadsDropdownActions: (ctx: UploadsDropdownActionsCtx) => Array<DropdownAction | DropdownActionGroup>;
 };
+type UploadsDropdownActionsCtx = Ctx;
+export {};

package/dist/types/manifestTypes.d.ts

@@ -1,51 +1,146 @@
+/**
+ * Type representing a manifest.
+ */
 export type Manifest = {
+    /**
+     * Hooks and their respective information.
+     */
     hooks: Record<string, HookInfo>;
+    /**
+     * Base properties and methods available on every context argument.
+     */
     baseCtx: {
-        properties: AdditionalPropertiesOrMethods;
-        methods: AdditionalPropertiesOrMethods;
+        /**
+         * Properties in the base context.
+         */
+        properties: AdditionalPropertiesOrMethodsGroup[];
+        /**
+         * Methods in the base context.
+         */
+        methods: AdditionalPropertiesOrMethodsGroup[];
     };
-    selfResizingPluginFrameCtxSizingUtilities: AdditionalPropertiesOrMethods;
+    /**
+     * Extra properties and methods available on every SelfResizingPluginFrameCtx context argument
+     */
+    selfResizingPluginFrameCtxSizingUtilities: AdditionalPropertiesOrMethodsGroup;
+};
+/**
+ * Type representing hook information.
+ */
+export type HookInfo = {
+    /**
+     * Name of the hook.
+     */
+    name: string;
+    /**
+     * JSDoc comment and tag for the hook.
+     */
+    comment?: Comment;
+    /**
+     * Non-context arguments for the hook.
+     */
+    nonCtxArguments: NonCtxArgument[];
+    /**
+     * Context argument for the hook, if any.
+     */
+    ctxArgument?: CtxArgument;
+    /**
+     * Return type of the hook function.
+     */
+    returnType: string;
+    /**
+     * Code location where the hook is defined.
+     */
+    location: CodeLocation;
+};
+/**
+ * Type representing a code location.
+ */
+export type CodeLocation = {
+    /**
+     * File path where the code is defined.
+     */
+    filePath: string;
+    /**
+     * Line number in the file where the hook is defined.
+     */
+    lineNumber: number;
 };
 /**
  * Type alias for additional parameters or methods in context.
  */
 export type AdditionalPropertyOrMethod = {
-    comment: Comment | null;
-    location: {
-        filePath: string;
-        lineNumber: number;
-    };
+    /**
+     * Description of the parameter or method.
+     */
+    comment?: Comment;
+    /**
+     * Code location where the parameter or method is defined.
+     */
+    location: CodeLocation;
+    /**
+     * Type of the parameter or method.
+     */
     type: string;
 };
-export type AdditionalPropertiesOrMethods = Record<string, AdditionalPropertyOrMethod>;
+export type AdditionalPropertiesOrMethodsGroup = {
+    /**
+     * Name of the group
+     */
+    name?: string;
+    /**
+     * Description of the group
+     */
+    comment?: Comment;
+    /**
+     * Type of the parameter or method.
+     */
+    items: Record<string, AdditionalPropertyOrMethod>;
+};
 /**
  * Type alias for the context argument extracted from hook type.
  */
 export type CtxArgument = {
+    /**
+     * Type of the context argument.
+     */
     type: string;
-    additionalProperties: AdditionalPropertiesOrMethods | null;
-    additionalMethods: AdditionalPropertiesOrMethods | null;
+    /**
+     * Additional properties in the context argument, if any.
+     */
+    additionalProperties?: AdditionalPropertiesOrMethodsGroup[];
+    /**
+     * Additional methods in the context argument, if any.
+     */
+    additionalMethods?: AdditionalPropertiesOrMethodsGroup[];
 };
 /**
  * Type alias for non-context arguments.
  */
 export type NonCtxArgument = {
+    /**
+     * Name of the non-context argument.
+     */
     name: string;
+    /**
+     * Type name of the non-context argument.
+     */
     typeName: string;
 };
-export interface HookInfo {
-    name: string;
-    comment: Comment | null;
-    nonCtxArguments: NonCtxArgument[];
-    ctxArgument: CtxArgument | null;
-    returnType: string;
-    location: {
-        filePath: string;
-        lineNumber: number;
-    };
-}
+/**
+ * Type representing a comment.
+ */
 export type Comment = {
+    /**
+     * The comment itself.
+     */
     comment: string;
+    /**
+     * JSDoc tag for the comment, if any.
+     */
     tag?: string;
+    /**
+     * Example or example code for the comment, if any.
+     */
     example?: string;
 };