datocms-plugin-sdk 1.1.1 → 2.0.0

package/src/ctx/commonExtras/field.ts

@@ -0,0 +1,27 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+
+type Field = SchemaTypes.Field;
+type ItemType = SchemaTypes.ItemType;
+
+export type FieldAdditionalProperties = {
+  /** Whether the field is currently disabled or not */
+  disabled: boolean;
+  /**
+   * The path in the `formValues` object where to find the current value for the
+   * field
+   */
+  fieldPath: string;
+  /** The field where the field extension is installed to */
+  field: Field;
+  /**
+   * If the field extension is installed in a field of a block, returns the top
+   * level Modular Content/Structured Text field containing the block itself
+   */
+  parentField: Field | undefined;
+  /**
+   * If the field extension is installed in a field of a block, returns the ID
+   * of the block — or `undefined` if the block is still not persisted — and the
+   * block model.
+   */
+  block: undefined | { id: string | undefined; blockModel: ItemType };
+};

package/src/ctx/commonExtras/itemForm.ts

@@ -0,0 +1,155 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+
+type Item = SchemaTypes.Item;
+type ItemType = SchemaTypes.ItemType;
+
+/**
+ * These information describe the current state of the form that's being shown
+ * to the end-user to edit a record
+ */
+export type ItemFormAdditionalProperties = {
+  /** The currently active locale for the record */
+  locale: string;
+  /**
+   * If an already persisted record is being edited, returns the full record
+   * entity
+   */
+  item: Item | null;
+  /** The model for the record being edited */
+  itemType: ItemType;
+  /** The complete internal form state */
+  formValues: Record<string, unknown>;
+  /** The current status of the record being edited */
+  itemStatus: 'new' | 'draft' | 'updated' | 'published';
+  /** Whether the form is currently submitting itself or not */
+  isSubmitting: boolean;
+  /** Whether the form has some non-persisted changes or not */
+  isFormDirty: boolean;
+  /** Current number of blocks present in form state */
+  blocksAnalysis: {
+    usage: {
+      /** Total number of blocks present in form state */
+      total: number;
+      /** Total number of blocks present in non-localized fields */
+      nonLocalized: number;
+      /** Total number of blocks present in localized fields, per locale */
+      perLocale: Record<string, number>;
+    };
+    /** Maximum number of blocks per item */
+    maximumPerItem: number;
+  };
+};
+
+/**
+ * These methods can be used to interact with the form that's being shown to the
+ * end-user to edit a record
+ */
+export type ItemFormAdditionalMethods = {
+  /**
+   * Hides/shows a specific field in the form. Please be aware that when a field
+   * is hidden, the field editor for that field will be removed from the DOM
+   * itself, including any associated plugins. When it is shown again, its
+   * plugins will be reinitialized.
+   *
+   * @example
+   *
+   * ```js
+   * const fieldPath = prompt(
+   *   'Please insert the path of a field in the form',
+   *   ctx.fieldPath,
+   * );
+   *
+   * await ctx.toggleField(fieldPath, true);
+   * ```
+   */
+  toggleField: (path: string, show: boolean) => Promise<void>;
+  /**
+   * Disables/re-enables a specific field in the form
+   *
+   * @example
+   *
+   * ```js
+   * const fieldPath = prompt(
+   *   'Please insert the path of a field in the form',
+   *   ctx.fieldPath,
+   * );
+   *
+   * await ctx.disableField(fieldPath, true);
+   * ```
+   */
+  disableField: (path: string, disable: boolean) => Promise<void>;
+  /**
+   * Smoothly navigates to a specific field in the form. If the field is
+   * localized it will switch language tab and then navigate to the chosen
+   * field.
+   *
+   * @example
+   *
+   * ```js
+   * const fieldPath = prompt(
+   *   'Please insert the path of a field in the form',
+   *   ctx.fieldPath,
+   * );
+   *
+   * await ctx.scrollToField(fieldPath);
+   * ```
+   */
+  scrollToField: (path: string, locale?: string) => Promise<void>;
+  /**
+   * Changes a specific path of the `formValues` object
+   *
+   * @example
+   *
+   * ```js
+   * const fieldPath = prompt(
+   *   'Please insert the path of a field in the form',
+   *   ctx.fieldPath,
+   * );
+   *
+   * await ctx.setFieldValue(fieldPath, 'new value');
+   * ```
+   */
+  setFieldValue: (path: string, value: unknown) => Promise<void>;
+  /**
+   * Takes the internal form state, and transforms it into an Item entity
+   * compatible with DatoCMS API.
+   *
+   * When `skipUnchangedFields`, only the fields that changed value will be
+   * serialized.
+   *
+   * If the required nested blocks are still not loaded, this method will return
+   * `undefined`.
+   *
+   * @example
+   *
+   * ```js
+   * await ctx.formValuesToItem(ctx.formValues, false);
+   * ```
+   */
+  formValuesToItem: (
+    formValues: Record<string, unknown>,
+    skipUnchangedFields?: boolean,
+  ) => Promise<Omit<Item, 'id' | 'meta'> | undefined>;
+  /**
+   * Takes an Item entity, and converts it into the internal form state
+   *
+   * @example
+   *
+   * ```js
+   * await ctx.itemToFormValues(ctx.item);
+   * ```
+   */
+  itemToFormValues: (
+    item: Omit<Item, 'id' | 'meta'>,
+  ) => Promise<Record<string, unknown>>;
+  /**
+   * Triggers a submit form for current record
+   *
+   * @example
+   *
+   * ```js
+   * await ctx.saveCurrentItem();
+   * ```
+   */
+  saveCurrentItem: (showToast?: boolean) => Promise<void>;
+};

package/src/ctx/commonExtras/sizing.ts

@@ -0,0 +1,27 @@
+export type SizingUtilities = {
+  /**
+   * Listens for DOM changes and automatically calls `setHeight` when it detects
+   * a change. If you're using `datocms-react-ui` package, the `<Canvas />`
+   * component already takes care of calling this method for you.
+   */
+  startAutoResizer: () => void;
+
+  /** Stops resizing the iframe automatically */
+  stopAutoResizer: () => void;
+
+  /**
+   * Triggers a change in the size of the iframe. If you don't explicitely pass
+   * a `newHeight` it will be automatically calculated using the iframe content
+   * at the moment
+   */
+  updateHeight: (newHeight?: number) => void;
+
+  /** Wheter the auto-resizer is currently active or not */
+  isAutoResizerActive(): boolean;
+};
+
+/** These methods can be used to set various properties of the containing iframe */
+export type IframeMethods = {
+  /** Sets the height for the iframe */
+  setHeight: (number: number) => Promise<void>;
+};

package/src/ctx/pluginFrame.ts

@@ -0,0 +1,39 @@
+import { FullConnectParameters } from '../connect';
+import { BaseMethods, BaseProperties } from './base';
+import { IframeMethods, SizingUtilities } from './commonExtras/sizing';
+
+export type ImposedSizePluginFrameCtx<
+  Mode extends keyof FullConnectParameters,
+  AdditionalProperties extends Record<string, unknown> = Record<string, never>,
+  AdditionalMethods extends Record<string, unknown> = Record<string, never>,
+> = BaseProperties &
+  PluginFrameAdditionalProperties<Mode> &
+  AdditionalProperties &
+  BaseMethods &
+  PluginFrameAdditionalMethods<
+    BaseProperties &
+      PluginFrameAdditionalProperties<Mode> &
+      AdditionalProperties
+  > &
+  AdditionalMethods;
+
+export type SelfResizingPluginFrameCtx<
+  Mode extends keyof FullConnectParameters,
+  AdditionalProperties extends Record<string, unknown> = Record<string, never>,
+  AdditionalMethods extends Record<string, unknown> = Record<string, never>,
+> = ImposedSizePluginFrameCtx<Mode, AdditionalProperties, AdditionalMethods> &
+  SizingUtilities &
+  IframeMethods;
+
+export type PluginFrameAdditionalProperties<
+  Mode extends keyof FullConnectParameters,
+> = {
+  mode: Mode;
+  bodyPadding: [number, number, number, number];
+};
+
+export type PluginFrameAdditionalMethods<
+  Properties extends Record<string, unknown>,
+> = {
+  getSettings: () => Promise<Properties>;
+};

package/src/hooks/assetSources.ts

@@ -0,0 +1,43 @@
+import { Ctx } from '../ctx/base';
+import { Icon } from '../icon';
+
+export type AssetSourcesHook = {
+  /**
+   * Use this function to declare additional sources to be shown when users want
+   * to upload new assets
+   *
+   * @tag assetSources
+   */
+  assetSources: (ctx: Ctx) => AssetSource[] | undefined;
+};
+
+/** An additional asset source */
+export type AssetSource = {
+  /**
+   * ID of the asset source. Will be the first argument for the
+   * `renderAssetSource` function
+   */
+  id: string;
+  /** Name of the asset that will be shown to the user */
+  name: string;
+  /**
+   * Icon to be shown alongside the name. 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;
+  /**
+   * Configuration options for the modal that will be opened to select a media
+   * file from this source
+   */
+  modal?: {
+    /** Width of the modal. Can be a number, or one of the predefined sizes */
+    width?: 's' | 'm' | 'l' | 'xl' | number;
+    /**
+     * The initial height to set for the iframe that will render the modal
+     * content
+     */
+    initialHeight?: number;
+  };
+};

package/src/hooks/buildItemPresentationInfo.ts

@@ -0,0 +1,33 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+import type { MaybePromise } from '../utils';
+
+type Item = SchemaTypes.Item;
+
+export type BuildItemPresentationInfoHook = {
+  /**
+   * Use this function to customize the presentation of a record in records
+   * collections and "Single link" or "Multiple links" field
+   *
+   * @tag presentation
+   */
+  buildItemPresentationInfo: (
+    item: Item,
+    ctx: Ctx,
+  ) => MaybePromise<ItemPresentationInfo | undefined>;
+};
+
+export type ItemPresentationInfo = {
+  /** The title to present the record */
+  title: string;
+  /** An image representative of the record */
+  imageUrl?: string;
+  /**
+   * If different plugins implement the `buildItemPresentationInfo` hook, the
+   * one with the lowest `rank` will be used. 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/contentAreaSidebarItems.ts

@@ -0,0 +1,41 @@
+import { Ctx } from '../ctx/base';
+import { Icon } from '../icon';
+
+export type ContentAreaSidebarItemsHook = {
+  /**
+   * Use this function to declare new items in the content area sidebar
+   *
+   * @tag sidebarItems
+   */
+  contentAreaSidebarItems: (ctx: Ctx) => ContentAreaSidebarItem[];
+};
+
+export type ContentAreaSidebarItem = {
+  /** 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;
+  };
+  /**
+   * Expresses where you want the item 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', 'menuItems' | 'seoPreferences'];
+  /**
+   * If different plugins specify the same `placement` for their panels, 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/customBlockStylesForStructuredTextField.ts

@@ -0,0 +1,42 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { BlockNodeTypeWithCustomStyle } from 'datocms-structured-text-utils';
+import { Ctx } from '../ctx/base';
+
+type Field = SchemaTypes.Field;
+type ItemType = SchemaTypes.ItemType;
+
+export type CustomBlockStylesForStructuredTextFieldHook = {
+  /**
+   * Use this function to define a number of custom block styles for a specific
+   * Structured Text field
+   *
+   * @tag structuredText
+   */
+  customBlockStylesForStructuredTextField: (
+    field: Field,
+    ctx: CustomBlockStylesForStructuredTextFieldHookCtx,
+  ) => StructuredTextCustomBlockStyle[] | undefined;
+};
+
+export type CustomBlockStylesForStructuredTextFieldHookCtx = Ctx<{
+  itemType: ItemType;
+}>;
+
+/** 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;
+};

package/src/hooks/customMarksForStructuredTextField.ts

@@ -0,0 +1,64 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+import { Icon } from '../icon';
+
+type Field = SchemaTypes.Field;
+type ItemType = SchemaTypes.ItemType;
+
+export type CustomMarksForStructuredTextFieldHook = {
+  /**
+   * Use this function to define a number of custom marks for a specific
+   * Structured Text field
+   *
+   * @tag structuredText
+   */
+  customMarksForStructuredTextField: (
+    field: Field,
+    ctx: CustomMarksForStructuredTextFieldHookCtx,
+  ) => StructuredTextCustomMark[] | undefined;
+};
+
+export type CustomMarksForStructuredTextFieldHookCtx = Ctx<{
+  itemType: ItemType;
+}>;
+
+/** 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;
+};
+
+export type StructuredTextCustomMarkPlacement = [
+  'before' | 'after',
+  'strong' | 'emphasis' | 'underline' | 'code' | 'highlight' | 'strikethrough',
+];

package/src/hooks/executeFieldDropdownAction.ts

@@ -0,0 +1,21 @@
+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>;
+};
+
+export type ExecuteFieldDropdownActionCtx = Ctx<
+  ItemFormAdditionalProperties &
+    FieldAdditionalProperties & {
+      parameters: Record<string, unknown> | undefined;
+    },
+  ItemFormAdditionalMethods
+>;

package/src/hooks/executeItemFormDropdownAction.ts

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

package/src/hooks/executeItemsDropdownAction.ts

@@ -0,0 +1,16 @@
+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>;
+};
+
+export type ExecuteItemsDropdownActionCtx = Ctx<{
+  parameters: Record<string, unknown> | undefined;
+}>;

package/src/hooks/executeUploadsDropdownAction.ts

@@ -0,0 +1,15 @@
+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>;
+};
+export type ExecuteUploadsDropdownActionCtx = Ctx<{
+  parameters: Record<string, unknown> | undefined;
+}>;

package/src/hooks/fieldDropdownActions.ts

@@ -0,0 +1,18 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+import { FieldAdditionalProperties } from '../ctx/commonExtras/field';
+import { ItemFormAdditionalProperties } from '../ctx/commonExtras/itemForm';
+import { DropdownAction, DropdownActionGroup } from '../shared';
+
+type Field = SchemaTypes.Field;
+
+export type FieldDropdownActionsHook = {
+  fieldDropdownActions: (
+    field: Field,
+    ctx: FieldDropdownActionsCtx,
+  ) => Array<DropdownAction | DropdownActionGroup>;
+};
+
+export type FieldDropdownActionsCtx = Ctx<
+  ItemFormAdditionalProperties & FieldAdditionalProperties
+>;

package/src/hooks/initialLocationQueryForItemSelector.ts

@@ -0,0 +1,33 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx, ItemListLocationQuery } from '../ctx/base';
+
+import { MaybePromise } from '../utils';
+
+type Field = SchemaTypes.Field;
+type ItemType = SchemaTypes.ItemType;
+
+export type InitialLocationQueryForItemSelectorHook = {
+  /**
+   * Use this function to customize the initial filters when opening a record
+   * selector via a "Single link" or "Multiple links" field
+   *
+   * @tag locationQuery
+   */
+  initialLocationQueryForItemSelector: (
+    openerField: Field,
+    itemType: ItemType,
+    ctx: Ctx,
+  ) => MaybePromise<InitialLocationQueryForItemSelector | undefined>;
+};
+
+export type InitialLocationQueryForItemSelector = {
+  locationQuery: ItemListLocationQuery;
+  /**
+   * If different plugins implement the `initialLocationQueryForItemSelector`
+   * hook, the one with the lowest `rank` will be used. 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/itemCollectionOutlets.ts

@@ -0,0 +1,29 @@
+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[];
+};
+
+/** An outlet to be shown at the top of a record's collection page */
+export type ItemCollectionOutlet = {
+  /**
+   * ID of the outlet. Will be the first argument for the `renderItemCollectionOutlet`
+   * 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/itemFormDropdownActions.ts

@@ -0,0 +1,18 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+import { ItemFormAdditionalProperties } from '../ctx/commonExtras/itemForm';
+import { DropdownAction, DropdownActionGroup } from '../shared';
+
+type ItemType = SchemaTypes.ItemType;
+
+export type ItemFormDropdownActionsHook = {
+  itemFormDropdownActions: (
+    itemType: ItemType,
+    ctx: ItemFormDropdownActionsCtx,
+  ) => Array<DropdownAction | DropdownActionGroup>;
+};
+
+export type ItemFormDropdownActionsCtx = ItemFormDropdownActionsProperties;
+
+export type ItemFormDropdownActionsProperties =
+  Ctx<ItemFormAdditionalProperties>;