datocms-plugin-sdk 0.4.0 → 0.5.0-alpha.2

package/src/connect.ts

@@ -23,7 +23,7 @@ import {
   RenderPageMethods,
   RenderPagePropertiesAndMethods,
   RenderSidebarPanelMethods,
-  RenderSidebarPanePropertiesAndMethods,
+  RenderSidebarPanelPropertiesAndMethods,
   SettingsAreaSidebarItemGroup,
 } from './types';
 import {
@@ -32,13 +32,20 @@ import {
   isRenderAssetSourceParent,
   isRenderConfigScreenParent,
   isRenderFieldExtensionParent,
+  isRenderItemFormOutletParent,
   isRenderManualFieldExtensionConfigScreenParent,
   isRenderModalParent,
   isRenderPageParent,
-  isRenderSidebarPaneParent,
+  isRenderSidebarPanelParent,
   Parent,
 } from './guards';
-import { StructuredTextCustomBlockStyle, StructuredTextCustomMark } from '.';
+import {
+  ItemFormOutlet,
+  RenderItemFormOutletMethods,
+  RenderItemFormOutletPropertiesAndMethods,
+  StructuredTextCustomBlockStyle,
+  StructuredTextCustomMark,
+} from '.';
 
 export type SizingUtilities = {
   /**
@@ -68,7 +75,9 @@ export type RenderPageCtx = RenderPagePropertiesAndMethods;
 export type RenderModalCtx = RenderModalPropertiesAndMethods & SizingUtilities;
 export type RenderAssetSourceCtx = RenderAssetSourcePropertiesAndMethods &
   SizingUtilities;
-export type RenderItemFormSidebarPanelCtx = RenderSidebarPanePropertiesAndMethods &
+export type RenderItemFormSidebarPanelCtx = RenderSidebarPanelPropertiesAndMethods &
+  SizingUtilities;
+export type RenderItemFormOutletCtx = RenderItemFormOutletPropertiesAndMethods &
   SizingUtilities;
 export type RenderFieldExtensionCtx = RenderFieldExtensionPropertiesAndMethods &
   SizingUtilities;
@@ -130,6 +139,15 @@ export type FullConnectParameters = {
     itemType: ModelBlock,
     ctx: IntentCtx,
   ) => ItemFormSidebarPanel[];
+
+  /**
+   * Use this function to declare custom outlets to be shown at the top of the
+   * record's editing page
+   *
+   * @group sidebarPanels
+   */
+  itemFormOutlets: (itemType: ModelBlock, ctx: IntentCtx) => ItemFormOutlet[];
+
   /**
    * Use this function to automatically force one or more field extensions to a
    * particular field
@@ -195,6 +213,16 @@ export type FullConnectParameters = {
     sidebarPaneId: string,
     ctx: RenderItemFormSidebarPanelCtx,
   ) => void;
+  /**
+   * This function will be called when the plugin needs to render an outlet (see
+   * the `itemFormOutlets` function)
+   *
+   * @group sidebarPanels
+   */
+  renderItemFormOutlet: (
+    itemFormOutletId: string,
+    ctx: RenderItemFormOutletCtx,
+  ) => void;
   /**
    * This function will be called when the user selects one of the plugin's
    * asset sources to upload a new media file.
@@ -338,6 +366,7 @@ export async function connect(
     contentAreaSidebarItems,
     manualFieldExtensions,
     itemFormSidebarPanels,
+    itemFormOutlets,
   } = configuration;
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -362,6 +391,7 @@ export async function connect(
       contentAreaSidebarItems,
       manualFieldExtensions,
       itemFormSidebarPanels,
+      itemFormOutlets,
       overrideFieldExtensions: toMultifield(
         configuration.overrideFieldExtensions,
       ),
@@ -487,7 +517,7 @@ export async function connect(
     render(initialSettings as Settings);
   }
 
-  if (isRenderSidebarPaneParent(parent, initialSettings)) {
+  if (isRenderSidebarPanelParent(parent, initialSettings)) {
     type Settings = AsyncReturnType<RenderSidebarPanelMethods['getSettings']>;
 
     const renderUtils = buildRenderUtils(parent);
@@ -508,6 +538,27 @@ export async function connect(
     render(initialSettings as Settings);
   }
 
+  if (isRenderItemFormOutletParent(parent, initialSettings)) {
+    type Settings = AsyncReturnType<RenderItemFormOutletMethods['getSettings']>;
+
+    const renderUtils = buildRenderUtils(parent);
+
+    const render = (settings: Settings) => {
+      if (!configuration.renderItemFormOutlet) {
+        return;
+      }
+
+      configuration.renderItemFormOutlet(settings.itemFormOutletId, {
+        ...parent,
+        ...settings,
+        ...renderUtils,
+      });
+    };
+
+    listener = render;
+    render(initialSettings as Settings);
+  }
+
   if (isRenderFieldExtensionParent(parent, initialSettings)) {
     type Settings = AsyncReturnType<RenderFieldExtensionMethods['getSettings']>;
 

package/src/guards.ts

@@ -1,3 +1,4 @@
+import { RenderItemFormOutletMethods } from '.';
 import {
   InitMethods,
   OnBootMethods,
@@ -31,10 +32,14 @@ export const isRenderModalParent = buildGuard<RenderModalMethods>(
   'renderModal',
 );
 
-export const isRenderSidebarPaneParent = buildGuard<RenderSidebarPanelMethods>(
+export const isRenderSidebarPanelParent = buildGuard<RenderSidebarPanelMethods>(
   'renderItemFormSidebarPanel',
 );
 
+export const isRenderItemFormOutletParent = buildGuard<RenderItemFormOutletMethods>(
+  'renderItemFormOutlet',
+);
+
 export const isRenderFieldExtensionParent = buildGuard<RenderFieldExtensionMethods>(
   'renderFieldExtension',
 );

package/src/types.ts

@@ -99,7 +99,7 @@ export type SettingsAreaSidebarItemGroup = {
    * will be displayed by ascending `rank`. If you want to specify an explicit
    * value for `rank`, make sure to offer a way for final users to customize it
    * inside the plugin's settings form, otherwise the hardcoded value you choose
-   * might clash with the one of another plugin! *
+   * might clash with the one of another plugin!
    */
   rank?: number;
 };
@@ -133,7 +133,7 @@ export type ContentAreaSidebarItem = {
    * will be displayed by ascending `rank`. If you want to specify an explicit
    * value for `rank`, make sure to offer a way for final users to customize it
    * inside the plugin's settings form, otherwise the hardcoded value you choose
-   * might clash with the one of another plugin! *
+   * might clash with the one of another plugin!
    */
   rank?: number;
 };
@@ -234,7 +234,22 @@ export type ItemFormSidebarPanel = {
    * sorted by ascending `rank`. If you want to specify an explicit value for
    * `rank`, make sure to offer a way for final users to customize it inside the
    * plugin's settings form, otherwise the hardcoded value you choose might
-   * clash with the one of another plugin! *
+   * clash with the one of another plugin!
+   */
+  rank?: number;
+  /** The initial height to set for the iframe that will render the sidebar panel */
+  initialHeight?: number;
+};
+
+/** An outlet to be shown at the top of a record's editing page */
+export type ItemFormOutlet = {
+  /** ID of the outlet. Will be the first argument for the `renderItemFormOutlet` function */
+  id: string;
+  /**
+   * Multiple outlets will be sorted by ascending `rank`. If you want to specify
+   * an explicit value for `rank`, make sure to offer a way for final users to
+   * customize it inside the plugin's settings form, otherwise the hardcoded
+   * value you choose might clash with the one of another plugin!
    */
   rank?: number;
   /** The initial height to set for the iframe that will render the sidebar panel */
@@ -262,7 +277,7 @@ export type EditorOverride = {
    * win. If you want to specify an explicit value for `rank`, make sure to
    * offer a way for final users to customize it inside the plugin's settings
    * form, otherwise the hardcoded value you choose might clash with the one of
-   * another plugin! *
+   * another plugin!
    */
   rank?: number;
   /** The initial height to set for the iframe that will render the field extension */
@@ -286,7 +301,7 @@ export type AddonOverride = {
    * ascending `rank`. If you want to specify an explicit value for `rank`, make
    * sure to offer a way for final users to customize it inside the plugin's
    * settings form, otherwise the hardcoded value you choose might clash with
-   * the one of another plugin! *
+   * the one of another plugin!
    */
   rank?: number;
   /** The initial height to set for the iframe that will render the field extension */
@@ -1202,9 +1217,29 @@ export type RenderSidebarPanelAdditionalMethods = {
 export type RenderSidebarPanelMethods = ItemFormMethods &
   RenderSidebarPanelAdditionalMethods;
 
-export type RenderSidebarPanePropertiesAndMethods = RenderSidebarPanelMethods &
+export type RenderSidebarPanelPropertiesAndMethods = RenderSidebarPanelMethods &
   RenderSidebarPanelProperties;
 
+/** Information regarding the specific outlet that you need to render */
+export type RenderItemFormOutletAdditionalProperties = {
+  mode: 'renderItemFormOutlet';
+  /** The ID of the outlet that needs to be rendered */
+  itemFormOutletId: string;
+};
+
+export type RenderItemFormOutletProperties = ItemFormProperties &
+  RenderItemFormOutletAdditionalProperties;
+
+export type RenderItemFormOutletAdditionalMethods = {
+  getSettings: () => Promise<RenderItemFormOutletProperties>;
+};
+
+export type RenderItemFormOutletMethods = ItemFormMethods &
+  RenderItemFormOutletAdditionalMethods;
+
+export type RenderItemFormOutletPropertiesAndMethods = RenderItemFormOutletMethods &
+  RenderItemFormOutletProperties;
+
 /**
  * Information regarding the state of a specific field where you need to render
  * the field extension