datocms-plugin-sdk 1.1.0 → 2.0.0

package/src/hooks/renderItemFormOutlet.ts

@@ -0,0 +1,40 @@
+import {
+  ItemFormAdditionalMethods,
+  ItemFormAdditionalProperties,
+} from '../ctx/commonExtras/itemForm';
+import { SelfResizingPluginFrameCtx } from '../ctx/pluginFrame';
+import { containedRenderModeBootstrapper } from '../utils';
+
+export type RenderItemFormOutletHook = {
+  /**
+   * This function will be called when the plugin needs to render an outlet (see
+   * the `itemFormOutlets` function)
+   *
+   * @tag itemFormOutlets
+   */
+  renderItemFormOutlet: (
+    itemFormOutletId: string,
+    ctx: RenderItemFormOutletCtx,
+  ) => void;
+};
+
+export type RenderItemFormOutletCtx = SelfResizingPluginFrameCtx<
+  'renderItemFormOutlet',
+  ItemFormAdditionalProperties & {
+    /** The ID of the outlet that needs to be rendered */
+    itemFormOutletId: string;
+  },
+  ItemFormAdditionalMethods
+>;
+
+export const renderItemFormOutletBootstrapper =
+  containedRenderModeBootstrapper<RenderItemFormOutletCtx>(
+    'renderItemFormOutlet',
+    (configuration, ctx) => {
+      if (!configuration.renderItemFormOutlet) {
+        return;
+      }
+
+      configuration.renderItemFormOutlet(ctx.itemFormOutletId, ctx);
+    },
+  );

package/src/hooks/renderItemFormSidebar.ts

@@ -0,0 +1,45 @@
+import {
+  ItemFormAdditionalMethods,
+  ItemFormAdditionalProperties,
+} from '../ctx/commonExtras/itemForm';
+import { ImposedSizePluginFrameCtx } from '../ctx/pluginFrame';
+import { fullScreenRenderModeBootstrapper } from '../utils';
+
+export type RenderItemFormSidebarHook = {
+  /**
+   * This function will be called when the plugin needs to render a sidebar (see
+   * the `itemFormSidebars` function)
+   *
+   * @tag sidebarPanels
+   */
+  renderItemFormSidebar: (
+    sidebarId: string,
+    ctx: RenderItemFormSidebarCtx,
+  ) => void;
+};
+
+export type RenderItemFormSidebarCtx = ImposedSizePluginFrameCtx<
+  'renderItemFormSidebar',
+  ItemFormAdditionalProperties & {
+    /** The ID of the sidebar that needs to be rendered */
+    sidebarId: string;
+    /**
+     * The arbitrary `parameters` of the declared in the `itemFormSidebars`
+     * function
+     */
+    parameters: Record<string, unknown>;
+  },
+  ItemFormAdditionalMethods
+>;
+
+export const renderItemFormSidebarBootstrapper =
+  fullScreenRenderModeBootstrapper<RenderItemFormSidebarCtx>(
+    'renderItemFormSidebar',
+    (configuration, ctx) => {
+      if (!configuration.renderItemFormSidebar) {
+        return;
+      }
+
+      configuration.renderItemFormSidebar(ctx.sidebarId, ctx);
+    },
+  );

package/src/hooks/renderItemFormSidebarPanel.ts

@@ -0,0 +1,46 @@
+import {
+  ItemFormAdditionalMethods,
+  ItemFormAdditionalProperties,
+} from '../ctx/commonExtras/itemForm';
+import { SelfResizingPluginFrameCtx } from '../ctx/pluginFrame';
+import { containedRenderModeBootstrapper } from '../utils';
+
+export type RenderItemFormSidebarPanelHook = {
+  /**
+   * This function will be called when the plugin needs to render a sidebar panel
+   * (see the `itemFormSidebarPanels` function)
+   *
+   * @tag sidebarPanels
+   */
+  renderItemFormSidebarPanel: (
+    sidebarPaneId: string,
+    ctx: RenderItemFormSidebarPanelCtx,
+  ) => void;
+};
+
+export type RenderItemFormSidebarPanelCtx = SelfResizingPluginFrameCtx<
+  'renderItemFormSidebarPanel',
+  ItemFormAdditionalProperties & {
+    /** The ID of the sidebar panel that needs to be rendered */
+    sidebarPaneId: string;
+
+    /**
+     * The arbitrary `parameters` of the panel declared in the
+     * `itemFormSidebarPanels` function
+     */
+    parameters: Record<string, unknown>;
+  },
+  ItemFormAdditionalMethods
+>;
+
+export const renderItemFormSidebarPanelBootstrapper =
+  containedRenderModeBootstrapper<RenderItemFormSidebarPanelCtx>(
+    'renderItemFormSidebarPanel',
+    (configuration, ctx) => {
+      if (!configuration.renderItemFormSidebarPanel) {
+        return;
+      }
+
+      configuration.renderItemFormSidebarPanel(ctx.sidebarPaneId, ctx);
+    },
+  );

package/src/hooks/renderManualFieldExtensionConfigScreen.ts

@@ -0,0 +1,83 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { SelfResizingPluginFrameCtx } from '../ctx/pluginFrame';
+import { containedRenderModeBootstrapper } from '../utils';
+
+type Field = SchemaTypes.Field;
+type ItemType = SchemaTypes.ItemType;
+
+export type RenderManualFieldExtensionConfigScreenHook = {
+  renderManualFieldExtensionConfigScreen: (
+    fieldExtensionId: string,
+    ctx: RenderManualFieldExtensionConfigScreenCtx,
+  ) => void;
+};
+
+export type RenderManualFieldExtensionConfigScreenCtx =
+  SelfResizingPluginFrameCtx<
+    'renderManualFieldExtensionConfigScreen',
+    {
+      /**
+       * The ID of the field extension for which we need to render the parameters
+       * form
+       */
+      fieldExtensionId: string;
+      /**
+       * The current value of the parameters (you can change the value with the
+       * `setParameters` function)
+       */
+      parameters: Record<string, unknown>;
+      /**
+       * The current validation errors for the parameters (you can set them
+       * implementing the `validateManualFieldExtensionParameters` function)
+       */
+      errors: Record<string, unknown>;
+
+      /** The field entity that is being edited in the form */
+      pendingField: PendingField;
+
+      /** The model for the field being edited */
+      itemType: ItemType;
+    },
+    {
+      /**
+       * Sets a new value for the parameters
+       *
+       * @example
+       *
+       * ```js
+       * await ctx.setParameters({ color: '#ff0000' });
+       * ```
+       */
+      setParameters: (params: Record<string, unknown>) => Promise<void>;
+    }
+  >;
+
+export type PendingField = {
+  id?: string;
+  type: 'field';
+  attributes: {
+    api_key: Field['attributes']['api_key'];
+    appearance: Field['attributes']['appearance'];
+    default_value: Field['attributes']['default_value'];
+    field_type: Field['attributes']['field_type'];
+    hint: Field['attributes']['hint'];
+    label: Field['attributes']['label'];
+    localized: Field['attributes']['localized'];
+    validators: Field['attributes']['validators'];
+  };
+};
+
+export const renderManualFieldExtensionConfigScreenBootstrapper =
+  containedRenderModeBootstrapper<RenderManualFieldExtensionConfigScreenCtx>(
+    'renderManualFieldExtensionConfigScreen',
+    (configuration, ctx) => {
+      if (!configuration.renderManualFieldExtensionConfigScreen) {
+        return;
+      }
+
+      configuration.renderManualFieldExtensionConfigScreen(
+        ctx.fieldExtensionId,
+        ctx,
+      );
+    },
+  );

package/src/hooks/renderModal.ts

@@ -0,0 +1,54 @@
+import { SelfResizingPluginFrameCtx } from '../ctx/pluginFrame';
+import { containedRenderModeBootstrapper } from '../utils';
+
+export type RenderModalHook = {
+  /**
+   * This function will be called when the plugin requested to open a modal (see
+   * the `openModal` function)
+   *
+   * @tag modals
+   */
+  renderModal: (modalId: string, ctx: RenderModalCtx) => void;
+};
+export type RenderModalCtx = SelfResizingPluginFrameCtx<
+  'renderModal',
+  {
+    /** The ID of the modal that needs to be rendered */
+    modalId: string;
+    /**
+     * The arbitrary `parameters` of the modal declared in the `openModal`
+     * function
+     */
+    parameters: Record<string, unknown>;
+  },
+  {
+    /**
+     * A function to be called by the plugin to close the modal. The `openModal`
+     * call will be resolved with the passed return value
+     *
+     * @example
+     *
+     * ```js
+     * const returnValue = prompt(
+     *   'Please specify the value to return to the caller:',
+     *   'success',
+     * );
+     *
+     * await ctx.resolve(returnValue);
+     * ```
+     */
+    resolve: (returnValue: unknown) => Promise<void>;
+  }
+>;
+
+export const renderModalBootstrapper =
+  containedRenderModeBootstrapper<RenderModalCtx>(
+    'renderModal',
+    (configuration, ctx) => {
+      if (!configuration.renderModal) {
+        return;
+      }
+
+      configuration.renderModal(ctx.modalId, ctx);
+    },
+  );

package/src/hooks/renderPage.ts

@@ -0,0 +1,33 @@
+import { ImposedSizePluginFrameCtx } from '../ctx/pluginFrame';
+import { fullScreenRenderModeBootstrapper } from '../utils';
+
+export type RenderPageHook = {
+  /**
+   * This function will be called when the plugin needs to render a specific
+   * page (see the `mainNavigationTabs`, `settingsAreaSidebarItemGroups` and
+   * `contentAreaSidebarItems` functions)
+   *
+   * @tag pages
+   */
+  renderPage: (pageId: string, ctx: RenderPageCtx) => void;
+};
+
+export type RenderPageCtx = ImposedSizePluginFrameCtx<
+  'renderPage',
+  {
+    /** The ID of the page that needs to be rendered */
+    pageId: string;
+  }
+>;
+
+export const renderPageBootstrapper =
+  fullScreenRenderModeBootstrapper<RenderPageCtx>(
+    'renderPage',
+    (configuration, ctx) => {
+      if (!configuration.renderPage) {
+        return;
+      }
+
+      configuration.renderPage(ctx.pageId, ctx);
+    },
+  );

package/src/hooks/renderUploadSidebar.ts

@@ -0,0 +1,44 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { ImposedSizePluginFrameCtx } from '../ctx/pluginFrame';
+import { fullScreenRenderModeBootstrapper } from '../utils';
+
+type Upload = SchemaTypes.Upload;
+
+export type RenderUploadSidebarHook = {
+  /**
+   * This function will be called when the plugin needs to render a sidebar (see
+   * the `uploadSidebars` function)
+   *
+   * @tag sidebarPanels
+   */
+  renderUploadSidebar: (sidebarId: string, ctx: RenderUploadSidebarCtx) => void;
+};
+
+export type RenderUploadSidebarCtx = ImposedSizePluginFrameCtx<
+  'renderUploadSidebar',
+  {
+    /** The ID of the sidebar that needs to be rendered */
+    sidebarId: string;
+
+    /**
+     * The arbitrary `parameters` of the declared in the `uploadSidebars`
+     * function
+     */
+    parameters: Record<string, unknown>;
+
+    /** The active asset */
+    upload: Upload;
+  }
+>;
+
+export const renderUploadSidebarBootstrapper =
+  fullScreenRenderModeBootstrapper<RenderUploadSidebarCtx>(
+    'renderUploadSidebar',
+    (configuration, ctx) => {
+      if (!configuration.renderUploadSidebar) {
+        return;
+      }
+
+      configuration.renderUploadSidebar(ctx.sidebarId, ctx);
+    },
+  );

package/src/hooks/renderUploadSidebarPanel.ts

@@ -0,0 +1,47 @@
+import { SchemaTypes } from '@datocms/cma-client';
+import { SelfResizingPluginFrameCtx } from '../ctx/pluginFrame';
+import { containedRenderModeBootstrapper } from '../utils';
+
+type Upload = SchemaTypes.Upload;
+
+export type RenderUploadSidebarPanelHook = {
+  /**
+   * This function will be called when the plugin needs to render a sidebar panel
+   * (see the `uploadSidebarPanels` function)
+   *
+   * @tag sidebarPanels
+   */
+  renderUploadSidebarPanel: (
+    sidebarPaneId: string,
+    ctx: RenderUploadSidebarPanelCtx,
+  ) => void;
+};
+
+export type RenderUploadSidebarPanelCtx = SelfResizingPluginFrameCtx<
+  'renderUploadSidebarPanel',
+  {
+    /** The ID of the sidebar panel that needs to be rendered */
+    sidebarPaneId: string;
+
+    /**
+     * The arbitrary `parameters` of the panel declared in the
+     * `uploadSidebarPanels` function
+     */
+    parameters: Record<string, unknown>;
+
+    /** The active asset */
+    upload: Upload;
+  }
+>;
+
+export const renderUploadSidebarPanelBootstrapper =
+  containedRenderModeBootstrapper<RenderUploadSidebarPanelCtx>(
+    'renderUploadSidebarPanel',
+    (configuration, ctx) => {
+      if (!configuration.renderUploadSidebarPanel) {
+        return;
+      }
+
+      configuration.renderUploadSidebarPanel(ctx.sidebarPaneId, ctx);
+    },
+  );

package/src/hooks/settingsAreaSidebarItemGroups.ts

@@ -0,0 +1,55 @@
+import { Ctx } from '../ctx/base';
+import { Icon } from '../icon';
+
+export type SettingsAreaSidebarItemGroupsHook = {
+  /**
+   * Use this function to declare new navigation sections in the Settings Area
+   * sidebar
+   *
+   * @tag pages
+   */
+  settingsAreaSidebarItemGroups: (ctx: Ctx) => SettingsAreaSidebarItemGroup[];
+};
+
+/**
+ * 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
+ * standard ones DatoCMS provides.
+ */
+export type SettingsAreaSidebarItemGroup = {
+  /** Label to be shown. Must be unique. */
+  label: string;
+  /** The list of items it contains * */
+  items: SettingsAreaSidebarItem[];
+  /**
+   * Expresses where you want the group to be placed inside the sidebar. If not
+   * specified, the item will be placed after the standard items provided by
+   * DatoCMS itself.
+   */
+  placement?: ['before' | 'after', 'properties' | 'permissions'];
+  /**
+   * If different plugins specify the same `placement` for their sections, they
+   * 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!
+   */
+  rank?: number;
+};
+
+/** An item contained in a Settings Area group */
+export type SettingsAreaSidebarItem = {
+  /** Label to be shown. Must be unique. */
+  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;
+  /** ID of the page linked to the item */
+  pointsTo: {
+    pageId: string;
+  };
+};

package/src/hooks/uploadSidebarPanels.ts

@@ -0,0 +1,57 @@
+import { Ctx } from '../ctx/base';
+
+export type UploadSidebarPanelsHook = {
+  /**
+   * Use this function to declare new sidebar panels to be shown when the user
+   * opens up an asset in the Media Area
+   *
+   * @tag sidebarPanels
+   */
+  uploadSidebarPanels: (ctx: Ctx) => UploadSidebarPanel[];
+};
+
+export type UploadSidebarPanel = {
+  /**
+   * ID of the panel. Will be the first argument for the
+   * `renderUploadSidebarPanel` function
+   */
+  id: string;
+  /** Label to be shown on the collapsible sidebar panel handle */
+  label: string;
+  /**
+   * An arbitrary configuration object that will be passed as the `parameters`
+   * property of the second argument of the `renderUploadSidebarPanel`
+   * function
+   */
+  parameters?: Record<string, unknown>;
+  /** Whether the sidebar panel will start open or collapsed */
+  startOpen?: boolean;
+  /**
+   * Expresses where you want the item to be placed inside the sidebar. If not
+   * specified, the item will be placed after the standard panels provided by
+   * DatoCMS itself.
+   */
+  placement?: UploadSidebarPanelPlacement;
+  /**
+   * If multiple sidebar panels specify the same `placement`, 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;
+  /** The initial height to set for the iframe that will render the sidebar panel */
+  initialHeight?: number;
+};
+
+export type UploadSidebarPanelPlacement = [
+  'before' | 'after',
+  (
+    | 'defaultMetadata'
+    | 'categorization'
+    | 'creator'
+    | 'videoTracks'
+    | 'links'
+    | 'replace'
+  ),
+];

package/src/hooks/uploadSidebars.ts

@@ -0,0 +1,36 @@
+import { Ctx } from '../ctx/base';
+
+export type UploadSidebarsHook = {
+  /**
+   * Use this function to declare new sidebar to be shown when the user opens
+   * up an asset in the Media Area
+   *
+   * @tag sidebarPanels
+   */
+  uploadSidebars: (ctx: Ctx) => UploadSidebar[];
+};
+
+export type UploadSidebar = {
+  /**
+   * ID of the sidebar. Will be the first argument for the
+   * `renderUploadSidebar` function
+   */
+  id: string;
+  /** Label to be shown on the collapsible sidebar handle */
+  label: string;
+  /**
+   * An arbitrary configuration object that will be passed as the `parameters`
+   * property of the second argument of the `renderUploadSidebar` function
+   */
+  parameters?: Record<string, unknown>;
+  /**
+   * If multiple sidebars specify the same `placement`, 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;
+  /** The preferred width for the sidebar */
+  preferredWidth?: number;
+};

package/src/hooks/uploadsDropdownActions.ts

@@ -0,0 +1,8 @@
+import { Ctx } from '../ctx/base';
+import { DropdownAction, DropdownActionGroup } from '../shared';
+
+export type UploadsDropdownActionsHook = {
+  uploadsDropdownActions: (
+    ctx: Ctx,
+  ) => Array<DropdownAction | DropdownActionGroup>;
+};

package/src/hooks/validateManualFieldExtensionParameters.ts

@@ -0,0 +1,12 @@
+export type ValidateManualFieldExtensionParametersHook = {
+  /**
+   * This function will be called each time the configuration object changes. It
+   * must return an object containing possible validation errors
+   *
+   * @tag manualFieldExtensions
+   */
+  validateManualFieldExtensionParameters: (
+    fieldExtensionId: string,
+    parameters: Record<string, unknown>,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>;
+};