datocms-plugin-sdk 1.1.1 → 2.0.0

package/src/hooks/itemFormOutlets.ts

@@ -0,0 +1,31 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+
+type ItemType = SchemaTypes.ItemType;
+
+export type ItemFormOutletsHook = {
+  /**
+   * Use this function to declare custom outlets to be shown at the top of the
+   * record's editing page
+   *
+   * @tag itemFormOutlets
+   */
+  itemFormOutlets: (itemType: ItemType, ctx: Ctx) => ItemFormOutlet[];
+};
+
+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 outlet */
+  initialHeight?: number;
+};

package/src/hooks/itemFormSidebarPanels.ts

@@ -0,0 +1,52 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+import { ItemFormSidebarPanelPlacement } from '../shared';
+
+type ItemType = SchemaTypes.ItemType;
+
+export type ItemFormSidebarPanelsHook = {
+  /**
+   * Use this function to declare new sidebar panels to be shown when the user
+   * edits records of a particular model
+   *
+   * @tag sidebarPanels
+   */
+  itemFormSidebarPanels: (
+    itemType: ItemType,
+    ctx: Ctx,
+  ) => ItemFormSidebarPanel[];
+};
+
+export type ItemFormSidebarPanel = {
+  /**
+   * ID of the panel. Will be the first argument for the
+   * `renderItemFormSidebarPanel` 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 `renderItemFormSidebarPanel`
+   * 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?: ItemFormSidebarPanelPlacement;
+  /**
+   * 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;
+};

package/src/hooks/itemFormSidebars.ts

@@ -0,0 +1,39 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+
+type ItemType = SchemaTypes.ItemType;
+
+export type ItemFormSidebarsHook = {
+  /**
+   * Use this function to declare new sidebar to be shown when the user edits
+   * records of a particular model
+   *
+   * @tag sidebarPanels
+   */
+  itemFormSidebars: (itemType: ItemType, ctx: Ctx) => ItemFormSidebar[];
+};
+
+export type ItemFormSidebar = {
+  /**
+   * ID of the sidebar. Will be the first argument for the
+   * `renderItemFormSidebar` 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 `renderItemFormSidebar` 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/itemsDropdownActions.ts

@@ -0,0 +1,16 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+import { DropdownAction, DropdownActionGroup } from '../shared';
+
+type ItemType = SchemaTypes.ItemType;
+
+export type ItemsDropdownActionsHook = {
+  itemsDropdownActions: (
+    itemType: ItemType,
+    ctx: ItemDropdownActionsCtx,
+  ) => Array<DropdownAction | DropdownActionGroup>;
+};
+
+export type ItemDropdownActionsCtx = Ctx<{
+  itemType: ItemType;
+}>;

package/src/hooks/mainNavigationTabs.ts

@@ -0,0 +1,45 @@
+import { Ctx } from '../ctx/base';
+import { Icon } from '../icon';
+
+export type MainNavigationTabsHook = {
+  /**
+   * Use this function to declare new tabs you want to add in the top-bar of the
+   * UI
+   *
+   * @tag pages
+   */
+  mainNavigationTabs: (ctx: Ctx) => MainNavigationTab[];
+};
+
+/** A tab to be displayed in the top-bar of the UI */
+export type MainNavigationTab = {
+  /** 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 tab */
+  pointsTo: {
+    pageId: string;
+  };
+  /**
+   * Expresses where you want to place the tab in the top-bar. If not specified,
+   * the tab will be placed after the standard tabs provided by DatoCMS itself.
+   */
+  placement?: [
+    'before' | 'after',
+    'content' | 'media' | 'schema' | 'configuration' | 'cdaPlayground',
+  ];
+  /**
+   * If different plugins specify the same `placement` for their tabs, 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;
+};

package/src/hooks/manualFieldExtensions.ts

@@ -0,0 +1,78 @@
+import { Ctx } from '../ctx/base';
+
+export type ManualFieldExtensionsHook = {
+  /**
+   * Use this function to declare new field extensions that users will be able
+   * to install manually in some field
+   *
+   * @tag manualFieldExtensions
+   */
+  manualFieldExtensions: (ctx: Ctx) => ManualFieldExtension[];
+};
+
+export type ManualFieldExtension = {
+  /**
+   * ID of field extension. Will be the first argument for the
+   * `renderFieldExtension` function
+   */
+  id: string;
+  /** Name to be shown when editing fields */
+  name: string;
+  /**
+   * Type of field extension. An `editor` extension replaces the default field
+   * editor that DatoCMS provides, while an `addon` extension is placed
+   * underneath the field editor to provide additional info/behaviour. You can
+   * setup multiple field addons for every field.
+   */
+  type: FieldExtensionType;
+  /**
+   * For `editor` extensions: moves the field to the sidebar of the record
+   * editing page, mimicking a sidebar panel
+   */
+  asSidebarPanel?: boolean | { startOpen: boolean };
+  /**
+   * The type of fields that the field extension in compatible with. You can use
+   * the shortcut `all` to target all types of fields
+   */
+  fieldTypes: 'all' | FieldType[];
+  /**
+   * Whether this field extension needs some configuration options before being
+   * installed in a field or not. Will trigger the
+   * `renderManualFieldExtensionConfigScreen` and
+   * `validateManualFieldExtensionParameters` methods
+   */
+  configurable?: boolean | { initialHeight: number };
+  /**
+   * The initial height to set for the iframe that will render the field
+   * extension
+   */
+  initialHeight?: number;
+};
+
+/**
+ * The sidebar in the Content Area presents a number of user-defined menu-items.
+ * This object represents a new item to be added in the sidebar.
+ */
+
+export type FieldExtensionType = 'editor' | 'addon';
+
+export type FieldType =
+  | 'boolean'
+  | 'color'
+  | 'date_time'
+  | 'date'
+  | 'file'
+  | 'float'
+  | 'gallery'
+  | 'integer'
+  | 'json'
+  | 'lat_lon'
+  | 'link'
+  | 'links'
+  | 'rich_text'
+  | 'seo'
+  | 'slug'
+  | 'string'
+  | 'structured_text'
+  | 'text'
+  | 'video';

package/src/hooks/onBeforeItemUpsert.ts

@@ -0,0 +1,19 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+import { MaybePromise } from '../utils';
+
+type ItemUpdateSchema = SchemaTypes.ItemUpdateSchema;
+type ItemCreateSchema = SchemaTypes.ItemCreateSchema;
+
+export type OnBeforeItemUpsertHook = {
+  /**
+   * This function will be called before saving a new version of a record. You
+   * can stop the action by returning `false`
+   *
+   * @tag beforeHooks
+   */
+  onBeforeItemUpsert: (
+    createOrUpdateItemPayload: ItemUpdateSchema | ItemCreateSchema,
+    ctx: Ctx,
+  ) => MaybePromise<boolean>;
+};

package/src/hooks/onBeforeItemsDestroy.ts

@@ -0,0 +1,15 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+import { MaybePromise } from '../utils';
+
+type Item = SchemaTypes.Item;
+
+export type OnBeforeItemsDestroyHook = {
+  /**
+   * This function will be called before destroying records. You can stop the
+   * action by returning `false`
+   *
+   * @tag beforeHooks
+   */
+  onBeforeItemsDestroy: (items: Item[], ctx: Ctx) => MaybePromise<boolean>;
+};

package/src/hooks/onBeforeItemsPublish.ts

@@ -0,0 +1,15 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+import { MaybePromise } from '../utils';
+
+type Item = SchemaTypes.Item;
+
+export type OnBeforeItemsPublishHook = {
+  /**
+   * This function will be called before publishing records. You can stop the
+   * action by returning `false`
+   *
+   * @tag beforeHooks
+   */
+  onBeforeItemsPublish: (items: Item[], ctx: Ctx) => MaybePromise<boolean>;
+};

package/src/hooks/onBeforeItemsUnpublish.ts

@@ -0,0 +1,15 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+import { MaybePromise } from '../utils';
+
+type Item = SchemaTypes.Item;
+
+export type OnBeforeItemsUnpublishHook = {
+  /**
+   * This function will be called before unpublishing records. You can stop the
+   * action by returning `false`
+   *
+   * @tag beforeHooks
+   */
+  onBeforeItemsUnpublish: (items: Item[], ctx: Ctx) => MaybePromise<boolean>;
+};

package/src/hooks/onBoot.ts

@@ -0,0 +1,13 @@
+import { ImposedSizePluginFrameCtx } from '../ctx/pluginFrame';
+
+export type OnBootHook = {
+  /**
+   * This function will be called once at boot time and can be used to perform
+   * ie. some initial integrity checks on the configuration.
+   *
+   * @tag boot
+   */
+  onBoot: (ctx: OnBootCtx) => void;
+};
+
+export type OnBootCtx = ImposedSizePluginFrameCtx<'onBoot'>;

package/src/hooks/overrideFieldExtensions.ts

@@ -0,0 +1,95 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+import { ItemFormSidebarPanelPlacement } from '../shared';
+
+type Field = SchemaTypes.Field;
+type ItemType = SchemaTypes.ItemType;
+
+export type OverrideFieldExtensionsHook = {
+  /**
+   * Use this function to automatically force one or more field extensions to a
+   * particular field
+   *
+   * @tag forcedFieldExtensions
+   */
+  overrideFieldExtensions: (
+    field: Field,
+    ctx: OverrideFieldExtensionsHookCtx,
+  ) => FieldExtensionOverride | undefined;
+};
+
+export type OverrideFieldExtensionsHookCtx = Ctx<{
+  itemType: ItemType;
+}>;
+
+/**
+ * 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 */
+  editor?: EditorOverride;
+  /** One or more field sidebar extensions to forcefully add to a field */
+  addons?: AddonOverride[];
+};
+
+/** A field editor/sidebar forced on a field */
+export type EditorOverride = {
+  /**
+   * ID of field extension. Will be the first argument for the
+   * `renderFieldExtension` function
+   */
+  id: string;
+  /**
+   * Moves the field to the sidebar of the record editing page, mimicking a
+   * sidebar panel
+   */
+  asSidebarPanel?:
+    | boolean
+    | { startOpen?: boolean; placement?: ItemFormSidebarPanelPlacement };
+  /**
+   * An arbitrary configuration object that will be passed as the `parameters`
+   * property of the second argument of the `renderFieldExtension` function
+   */
+  parameters?: Record<string, unknown>;
+  /**
+   * If multiple plugins override a field, the one with the lowest `rank` will
+   * 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!
+   */
+  rank?: number;
+  /**
+   * The initial height to set for the iframe that will render the field
+   * extension
+   */
+  initialHeight?: number;
+};
+
+/** A field addon extension forced on a field */
+export type AddonOverride = {
+  /**
+   * ID of field extension. Will be the first argument for the
+   * `renderFieldExtension` function
+   */
+  id: string;
+  /**
+   * An arbitrary configuration object that will be passed as the `parameters`
+   * property of the second argument of the `renderFieldExtension` function
+   */
+  parameters?: Record<string, unknown>;
+  /**
+   * If multiple addons are present for a field, 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 field
+   * extension
+   */
+  initialHeight?: number;
+};

package/src/hooks/renderAssetSource.ts

@@ -0,0 +1,119 @@
+import { SelfResizingPluginFrameCtx } from '../ctx/pluginFrame';
+import { containedRenderModeBootstrapper } from '../utils';
+
+export type RenderAssetSourceHook = {
+  /**
+   * This function will be called when the user selects one of the plugin's
+   * asset sources to upload a new media file.
+   *
+   * @tag assetSources
+   */
+  renderAssetSource: (assetSourceId: string, ctx: RenderAssetSourceCtx) => void;
+};
+
+export type RenderAssetSourceCtx = SelfResizingPluginFrameCtx<
+  'renderAssetSource',
+  {
+    /** The ID of the assetSource that needs to be rendered */
+    assetSourceId: string;
+  },
+  {
+    /**
+     * Function to be called when the user selects the asset: it will trigger the
+     * creation of a new `Upload` that will be added in the Media Area.
+     *
+     * @example
+     *
+     * ```js
+     * await ctx.select({
+     *   resource: {
+     *     url: 'https://images.unsplash.com/photo-1416339306562-f3d12fefd36f',
+     *     filename: 'man-drinking-coffee.jpg',
+     *   },
+     *   copyright: 'Royalty free (Unsplash)',
+     *   author: 'Jeff Sheldon',
+     *   notes: 'A man drinking a coffee',
+     *   tags: ['man', 'coffee'],
+     * });
+     * ```
+     */
+    select: (newUpload: NewUpload) => void;
+  }
+>;
+
+export type NewUploadResourceAsUrl = {
+  /**
+   * URL for the resource. The URL must respond with a
+   * `Access-Control-Allow-Origin` header — for instance `*`, which will allow
+   * all hosts — allowing the image to be read by DatoCMS
+   */
+  url: string;
+  /** Any additional headers to pass when making the request to the URL */
+  headers?: Record<string, string>;
+  /**
+   * Optional filename to be used to generate the final DatoCMS URL. If not
+   * passed, the URL will be used
+   */
+  filename?: string;
+};
+
+export type NewUploadResourceAsBase64 = {
+  /**
+   * Base64 encoded data URI for the resource.
+   *
+   * Format:
+   *
+   * `data:[<mime type>][;charset=<charset>];base64,<encoded data>`
+   */
+  base64: string;
+  /** Filename to be used to generate the final DatoCMS URL */
+  filename: string;
+};
+
+export type NewUpload = {
+  /** The actual resource that will be uploaded */
+  resource: NewUploadResourceAsUrl | NewUploadResourceAsBase64;
+  /** Copyright to apply to the asset */
+  copyright?: string;
+  /** Author to apply to the asset */
+  author?: string;
+  /** Notes to apply to the asset */
+  notes?: string;
+  /** Tags to apply to the asset */
+  tags?: string[];
+  /**
+   * An hash containing, for each locale of the project, the default metadata to
+   * apply to the asset
+   */
+  default_field_metadata?: {
+    [k: string]: {
+      /** Alternate text for the asset */
+      alt: string | null;
+      /** Title for the asset */
+      title: string | null;
+      /** Object with arbitrary metadata */
+      custom_data: {
+        [k: string]: unknown;
+      };
+      /** Focal point (only for image assets) */
+      focal_point?: {
+        /** Horizontal position expressed as float between 0 and 1 */
+        x: number;
+        /** Vertical position expressed as float between 0 and 1 */
+        y: number;
+      } | null;
+    };
+  };
+};
+
+export const renderAssetSourceBootstrapper =
+  containedRenderModeBootstrapper<RenderAssetSourceCtx>(
+    'renderAssetSource',
+    (configuration, ctx) => {
+      if (!configuration.renderAssetSource) {
+        return;
+      }
+
+      configuration.renderAssetSource(ctx.assetSourceId, ctx);
+    },
+  );

package/src/hooks/renderConfigScreen.ts

@@ -0,0 +1,27 @@
+import { SelfResizingPluginFrameCtx } from '../ctx/pluginFrame';
+import { containedRenderModeBootstrapper } from '../utils';
+
+export type RenderConfigScreenHook = {
+  /**
+   * This function will be called when the plugin needs to render the plugin's
+   * configuration form
+   *
+   * @tag configScreen
+   */
+  renderConfigScreen: (ctx: RenderConfigScreenCtx) => void;
+};
+
+export type RenderConfigScreenCtx =
+  SelfResizingPluginFrameCtx<'renderConfigScreen'>;
+
+export const renderConfigScreenBootstrapper =
+  containedRenderModeBootstrapper<RenderConfigScreenCtx>(
+    'renderConfigScreen',
+    (configuration, ctx) => {
+      if (!configuration.renderConfigScreen) {
+        return;
+      }
+
+      configuration.renderConfigScreen(ctx);
+    },
+  );

package/src/hooks/renderFieldExtension.ts

@@ -0,0 +1,46 @@
+import { FieldAdditionalProperties } from '../ctx/commonExtras/field';
+import {
+  ItemFormAdditionalMethods,
+  ItemFormAdditionalProperties,
+} from '../ctx/commonExtras/itemForm';
+
+import { SelfResizingPluginFrameCtx } from '../ctx/pluginFrame';
+import { containedRenderModeBootstrapper } from '../utils';
+
+export type RenderFieldExtensionHook = {
+  /**
+   * This function will be called when the plugin needs to render a field
+   * extension (see the `manualFieldExtensions` and `overrideFieldExtensions`
+   * functions)
+   *
+   * @tag forcedFieldExtensions
+   */
+  renderFieldExtension: (
+    fieldExtensionId: string,
+    ctx: RenderFieldExtensionCtx,
+  ) => void;
+};
+
+export type RenderFieldExtensionCtx = SelfResizingPluginFrameCtx<
+  'renderFieldExtension',
+  ItemFormAdditionalProperties &
+    FieldAdditionalProperties & {
+      /** The ID of the field extension that needs to be rendered */
+      fieldExtensionId: string;
+      /** The arbitrary `parameters` of the field extension */
+      parameters: Record<string, unknown>;
+    },
+  ItemFormAdditionalMethods
+>;
+
+export const renderFieldExtensionBootstrapper =
+  containedRenderModeBootstrapper<RenderFieldExtensionCtx>(
+    'renderFieldExtension',
+    (configuration, ctx) => {
+      if (!configuration.renderFieldExtension) {
+        return;
+      }
+
+      configuration.renderFieldExtension(ctx.fieldExtensionId, ctx);
+    },
+  );

package/src/hooks/renderItemCollectionOutlet.ts

@@ -0,0 +1,29 @@
+import { SelfResizingPluginFrameCtx } from '../ctx/pluginFrame';
+import { containedRenderModeBootstrapper } from '../utils';
+
+export type RenderItemCollectionOutletHook = {
+  renderItemCollectionOutlet: (
+    itemCollectionOutletId: string,
+    ctx: RenderItemCollectionOutletCtx,
+  ) => void;
+};
+
+export type RenderItemCollectionOutletCtx = SelfResizingPluginFrameCtx<
+  'renderItemCollectionOutlet',
+  {
+    /** The ID of the outlet that needs to be rendered */
+    itemCollectionOutletId: string;
+  }
+>;
+
+export const renderItemCollectionOutletBootstrapper =
+  containedRenderModeBootstrapper<RenderItemCollectionOutletCtx>(
+    'renderItemCollectionOutlet',
+    (configuration, ctx) => {
+      if (!configuration.renderItemCollectionOutlet) {
+        return;
+      }
+
+      configuration.renderItemCollectionOutlet(ctx.itemCollectionOutletId, ctx);
+    },
+  );