datocms-plugin-sdk 0.3.34 → 0.5.0-alpha.0

package/dist/types/types.d.ts

@@ -1,3 +1,5 @@
+/// <reference types="react" />
+import { BlockNodeTypeWithCustomStyle } from 'datocms-structured-text-utils';
 import { Account, Field, Fieldset, Item, ModelBlock, Plugin, Role, Site, SsoUser, Upload, User } from './SiteApiSchema';
 export declare type Icon = string | {
     type: 'svg';
@@ -32,7 +34,7 @@ export declare type MainNavigationTab = {
      * 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! *
+     * clash with the one of another plugin!
      */
     rank?: number;
 };
@@ -76,7 +78,7 @@ export declare 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;
 };
@@ -109,7 +111,7 @@ export declare 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;
 };
@@ -190,7 +192,21 @@ export declare 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 declare 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 */
@@ -218,7 +234,7 @@ export declare 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 */
@@ -241,12 +257,69 @@ export declare 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 */
     initialHeight?: number;
 };
+export declare type StructuredTextCustomMarkPlacement = [
+    'before' | 'after',
+    'strong' | 'emphasis' | 'underline' | 'code' | 'highlight' | 'strikethrough'
+];
+/** An object expressing a custom mark for a Structured Text field */
+export declare type StructuredTextCustomMark = {
+    /** ID of mark */
+    id: string;
+    /** Label representing the custom mark */
+    label: string;
+    /**
+     * Icon to be shown alongside the label. Can be a FontAwesome icon name (ie.
+     * `"address-book"`) or a custom SVG definition. To maintain visual
+     * consistency with the rest of the interface, try to use FontAwesome icons
+     * whenever possible
+     */
+    icon: Icon;
+    /**
+     * Expresses where you want the custom mark button to be placed inside the
+     * toolbar. If not specified, the item will be placed after the standard marks
+     * provided by DatoCMS itself.
+     */
+    placement?: StructuredTextCustomMarkPlacement;
+    /**
+     * If multiple custom marks specify the same `placement` for their toolbar
+     * button, they 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;
+    /**
+     * Keyboard shortcut associated with the custom mark, expressed using the
+     * https://github.com/ianstormtaylor/is-hotkey syntax (ie. `mod+shift+x`)
+     */
+    keyboardShortcut?: string;
+    /** How the custom mark will be styled inside the editor */
+    appliedStyle: React.CSSProperties;
+};
+/** An object expressing a custom block style for a Structured Text field */
+export declare type StructuredTextCustomBlockStyle = {
+    /** ID of custom block style */
+    id: string;
+    /** The block node that can apply this style */
+    node: BlockNodeTypeWithCustomStyle;
+    /** ID of custom block style */
+    label: string;
+    /** How the block will be styled inside the editor to represent the style */
+    appliedStyle: React.CSSProperties;
+    /**
+     * Custom styles for a block node 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;
+};
 /** An object expressing some field extensions you want to force on a particular field */
 export declare type FieldExtensionOverride = {
     /** Force a field editor/sidebar extension on a field */
@@ -1043,7 +1116,21 @@ export declare type RenderSidebarPanelAdditionalMethods = {
     getSettings: () => Promise<RenderSidebarPanelProperties>;
 };
 export declare type RenderSidebarPanelMethods = ItemFormMethods & RenderSidebarPanelAdditionalMethods;
-export declare type RenderSidebarPanePropertiesAndMethods = RenderSidebarPanelMethods & RenderSidebarPanelProperties;
+export declare type RenderSidebarPanelPropertiesAndMethods = RenderSidebarPanelMethods & RenderSidebarPanelProperties;
+/** Information regarding the specific outlet that you need to render */
+export declare type RenderItemFormOutletAdditionalProperties = {
+    mode: 'renderItemFormItemFormOutlet';
+    /** The ID of the outlet that needs to be rendered */
+    itemFormOutletId: string;
+    /** The arbitrary `parameters` of the panel declared in the `itemFormOutlets` function */
+    parameters: Record<string, unknown>;
+};
+export declare type RenderItemFormOutletProperties = ItemFormProperties & RenderItemFormOutletAdditionalProperties;
+export declare type RenderItemFormOutletAdditionalMethods = {
+    getSettings: () => Promise<RenderItemFormOutletProperties>;
+};
+export declare type RenderItemFormOutletMethods = ItemFormMethods & RenderItemFormOutletAdditionalMethods;
+export declare type RenderItemFormOutletPropertiesAndMethods = RenderItemFormOutletMethods & RenderItemFormOutletProperties;
 /**
  * Information regarding the state of a specific field where you need to render
  * the field extension

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datocms-plugin-sdk",
-  "version": "0.3.34",
+  "version": "0.5.0-alpha.0",
   "description": "DatoCMS Plugin SDK",
   "keywords": [
     "datocms",
@@ -36,10 +36,12 @@
     "url": "https://github.com/datocms/plugins-sdk/issues"
   },
   "dependencies": {
+    "@types/react": "^17.0.3",
+    "datocms-structured-text-utils": "^2.0.0",
     "penpal": "^4.1.1"
   },
   "devDependencies": {
     "typedoc": "^0.22.8"
   },
-  "gitHead": "6d45ff0912ff738fec1e5e74662b7a166d578082"
+  "gitHead": "cbc2c3c6a3ce9438460435746cdd27e636ad261a"
 }

package/src/connect.ts

@@ -23,7 +23,7 @@ import {
   RenderPageMethods,
   RenderPagePropertiesAndMethods,
   RenderSidebarPanelMethods,
-  RenderSidebarPanePropertiesAndMethods,
+  RenderSidebarPanelPropertiesAndMethods,
   SettingsAreaSidebarItemGroup,
 } from './types';
 import {
@@ -32,12 +32,20 @@ import {
   isRenderAssetSourceParent,
   isRenderConfigScreenParent,
   isRenderFieldExtensionParent,
+  isRenderItemFormOutletParent,
   isRenderManualFieldExtensionConfigScreenParent,
   isRenderModalParent,
   isRenderPageParent,
-  isRenderSidebarPaneParent,
+  isRenderSidebarPanelParent,
   Parent,
 } from './guards';
+import {
+  ItemFormOutlet,
+  RenderItemFormOutletMethods,
+  RenderItemFormOutletPropertiesAndMethods,
+  StructuredTextCustomBlockStyle,
+  StructuredTextCustomMark,
+} from '.';
 
 export type SizingUtilities = {
   /**
@@ -67,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;
@@ -129,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
@@ -139,6 +158,29 @@ export type FullConnectParameters = {
     field: Field,
     ctx: FieldIntentCtx,
   ) => FieldExtensionOverride | void;
+
+  /**
+   * Use this function to define a number of custom marks for a specific
+   * Structured Text field
+   *
+   * @group structuredText
+   */
+  customMarksForStructuredTextField: (
+    field: Field,
+    ctx: FieldIntentCtx,
+  ) => StructuredTextCustomMark[] | void;
+
+  /**
+   * Use this function to define a number of custom block styles for a specific
+   * Structured Text field
+   *
+   * @group structuredText
+   */
+  customBlockStylesForStructuredTextField: (
+    field: Field,
+    ctx: FieldIntentCtx,
+  ) => StructuredTextCustomBlockStyle[] | void;
+
   /**
    * This function will be called when the plugin needs to render the plugin's
    * configuration form
@@ -171,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.
@@ -341,6 +393,12 @@ export async function connect(
       overrideFieldExtensions: toMultifield(
         configuration.overrideFieldExtensions,
       ),
+      customMarksForStructuredTextField: toMultifield(
+        configuration.customMarksForStructuredTextField,
+      ),
+      customBlockStylesForStructuredTextField: toMultifield(
+        configuration.customBlockStylesForStructuredTextField,
+      ),
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       onChange(newSettings: any) {
         if (listener) {
@@ -457,7 +515,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);
@@ -478,6 +536,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

@@ -1,3 +1,5 @@
+import { BlockNodeTypeWithCustomStyle } from 'datocms-structured-text-utils';
+
 import {
   Account,
   Field,
@@ -42,7 +44,7 @@ export type MainNavigationTab = {
    * 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! *
+   * clash with the one of another plugin!
    */
   rank?: number;
 };
@@ -97,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;
 };
@@ -131,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;
 };
@@ -232,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 */
@@ -260,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 */
@@ -284,13 +301,73 @@ 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 */
   initialHeight?: number;
 };
 
+export type StructuredTextCustomMarkPlacement = [
+  'before' | 'after',
+  'strong' | 'emphasis' | 'underline' | 'code' | 'highlight' | 'strikethrough',
+];
+
+/** An object expressing a custom mark for a Structured Text field */
+export type StructuredTextCustomMark = {
+  /** ID of mark */
+  id: string;
+  /** Label representing the custom mark */
+  label: string;
+  /**
+   * Icon to be shown alongside the label. Can be a FontAwesome icon name (ie.
+   * `"address-book"`) or a custom SVG definition. To maintain visual
+   * consistency with the rest of the interface, try to use FontAwesome icons
+   * whenever possible
+   */
+  icon: Icon;
+  /**
+   * Expresses where you want the custom mark button to be placed inside the
+   * toolbar. If not specified, the item will be placed after the standard marks
+   * provided by DatoCMS itself.
+   */
+  placement?: StructuredTextCustomMarkPlacement;
+  /**
+   * If multiple custom marks specify the same `placement` for their toolbar
+   * button, they 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;
+  /**
+   * Keyboard shortcut associated with the custom mark, expressed using the
+   * https://github.com/ianstormtaylor/is-hotkey syntax (ie. `mod+shift+x`)
+   */
+  keyboardShortcut?: string;
+  /** How the custom mark will be styled inside the editor */
+  appliedStyle: React.CSSProperties;
+};
+
+/** An object expressing a custom block style for a Structured Text field */
+export type StructuredTextCustomBlockStyle = {
+  /** ID of custom block style */
+  id: string;
+  /** The block node that can apply this style */
+  node: BlockNodeTypeWithCustomStyle;
+  /** ID of custom block style */
+  label: string;
+  /** How the block will be styled inside the editor to represent the style */
+  appliedStyle: React.CSSProperties;
+  /**
+   * Custom styles for a block node 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;
+};
+
 /** An object expressing some field extensions you want to force on a particular field */
 export type FieldExtensionOverride = {
   /** Force a field editor/sidebar extension on a field */
@@ -1140,9 +1217,31 @@ 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: 'renderItemFormItemFormOutlet';
+  /** The ID of the outlet that needs to be rendered */
+  itemFormOutletId: string;
+  /** The arbitrary `parameters` of the panel declared in the `itemFormOutlets` function */
+  parameters: Record<string, unknown>;
+};
+
+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