datocms-plugin-sdk 2.1.0-alpha.0 → 2.1.0-alpha.2

package/src/hooks/mainNavigationTabs.ts

@@ -36,10 +36,26 @@ export type MainNavigationTab = {
    * whenever possible.
    */
   icon: Icon;
-  /** ID of the page linked to the tab */
-  pointsTo: {
-    pageId: string;
-  };
+  /** ID of the page/inspector linked to the tab */
+  pointsTo:
+    | {
+        pageId: string;
+      }
+    | {
+        inspectorId: string;
+        /** The preferred width for the sidebar */
+        preferredWidth?: number;
+        /** The inspector panel to render when first loaded */
+        initialInspectorPanel?: {
+          /** ID of the inspector panel to render */
+          panelId: string;
+          /**
+           * An arbitrary configuration object that will be passed as the `parameters`
+           * property of the second argument of the `renderInspectorPanel` function
+           */
+          parameters?: Record<string, unknown>;
+        };
+      };
   /**
    * 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.
@@ -66,7 +82,10 @@ export function isMainNavigationTab(
     isString(value.label) &&
     isIcon(value.icon) &&
     isRecord(value.pointsTo) &&
-    isString(value.pointsTo.pageId) &&
+    (isString(value.pointsTo.pageId) ||
+      (isString(value.pointsTo.inspectorId) &&
+        (isNullish(value.pointsTo.preferredWidth) ||
+          isNumber(value.pointsTo.preferredWidth)))) &&
     (isNullish(value.placement) || isPlacement(value.placement)) &&
     (isNullish(value.rank) || isNumber(value.rank))
   );

package/src/hooks/onBeforeItemUpsert.ts

@@ -7,8 +7,15 @@ 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`
+   * This hook is called when the user attempts to save a record. You can use it to block record saving.
+   *
+   * If you return `false`, the record will NOT be saved. A small on-page error will say "A plugin blocked the action".
+   * However, for better UX, consider also using `ctx.alert()` to better explain to the user why their save was blocked.
+   *
+   * If you return `true`, the save will proceed as normal.
+   *
+   * This hook runs BEFORE serverside validation. You can use it to do your own additional validation before returning.
+   * Clientside validations are not affected by this hook, since those occur on individual fields' `onBlur()` events.
    *
    * @tag beforeHooks
    */
@@ -18,4 +25,25 @@ export type OnBeforeItemUpsertHook = {
   ) => MaybePromise<boolean>;
 };
 
-export type OnBeforeItemUpsertCtx = Ctx;
+export type OnBeforeItemUpsertCtx = Ctx<
+  {},
+  {
+    /**
+     * 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>;
+  }
+>;

package/src/hooks/renderInspector.ts

@@ -0,0 +1,176 @@
+import { ImposedSizePluginFrameCtx } from '../ctx/pluginFrame';
+import { fullScreenRenderModeBootstrapper } from '../utils';
+
+/**
+ * Defines the different modes in which an inspector can be displayed
+ */
+export type InspectorMode =
+  | {
+      /** Display a list of records in the inspector */
+      type: 'itemList';
+    }
+  | {
+      /** Display a single record editor in the inspector */
+      type: 'itemEditor';
+      /** The ID of the record to edit */
+      itemId: string;
+      /** Optional field path to highlight/focus within the record editor */
+      fieldPath?: string;
+    }
+  | {
+      /** Display a custom panel in the inspector */
+      type: 'customPanel';
+      /** ID of the inspector panel to render */
+      panelId: string;
+      /**
+       * An arbitrary configuration object that will be passed as the `parameters`
+       * property of the second argument of the `renderInspectorPanel` function
+       */
+      parameters?: Record<string, unknown>;
+    };
+
+/**
+ * Options for configuring inspector mode changes
+ */
+export type SetInspectorModeOptions = {
+  /**
+   * When true, the mode change will be ignored if there are unsaved changes
+   * in the current inspector. Useful for "low intent" mode changes that
+   * shouldn't interrupt active editing sessions.
+   * @default false
+   */
+  ignoreIfUnsavedChanges?: boolean;
+};
+
+export type RenderInspectorHook = {
+  /**
+   * This function will be called when the plugin needs to render a specific
+   * inspector. Inspectors provide a side panel interface for displaying and
+   * interacting with content alongside a custom interface.
+   *
+   * @tag inspector
+   *
+   * @example
+   *
+   * ```js
+   * connect({
+   *   renderInspector(inspectorId, ctx) {
+   *     render(
+   *       <div>
+   *         <h1>Inspector: {inspectorId}</h1>
+   *         <button onClick={() => ctx.setInspectorMode({
+   *           type: 'itemEditor',
+   *           itemId: 'some-item-id'
+   *         })}>
+   *           Show Item Editor
+   *         </button>
+   *       </div>
+   *     );
+   *   }
+   * });
+   * ```
+   */
+  renderInspector: (inspectorId: string, ctx: RenderInspectorCtx) => void;
+};
+
+export type RenderInspectorCtx = ImposedSizePluginFrameCtx<
+  'renderInspector',
+  {
+    /** The ID of the inspector that needs to be rendered */
+    inspectorId: string;
+
+    /** The ID of the record the currently is highlighted by the user */
+    highlightedItemId: string | undefined;
+
+    /** Current page location */
+    location: {
+      pathname: string;
+      search: string;
+      hash: string;
+    };
+  },
+  {
+    /**
+     * Changes the current display mode of the inspector. This allows the plugin
+     * to dynamically switch between showing a record list, record editor, or custom
+     * panel within the inspector interface.
+     *
+     * @param mode - The inspector mode to switch to
+     * @param options - Optional configuration for the mode change
+     * @param options.ignoreIfUnsavedChanges - When true, the mode change request will be
+     * ignored if the current inspector is in itemEditor mode and has unsaved changes.
+     * This allows for "low intent" mode changes that shouldn't interrupt active editing.
+     * Default is false, meaning mode changes will proceed regardless of unsaved changes.
+     *
+     * @example
+     *
+     * ```js
+     * // Switch to record editor mode
+     * await ctx.setInspectorMode({
+     *   type: 'itemEditor',
+     *   itemId: 'item-123',
+     *   fieldPath: 'title'
+     * });
+     *
+     * // Switch to record list mode
+     * await ctx.setInspectorMode({ type: 'itemList' });
+     * await ctx.setInspectorItemListData({
+     *   title: 'Related Records',
+     *   itemIds: ['item-1', 'item-2', 'item-3']
+     * });
+     *
+     * // Switch to custom panel mode
+     * await ctx.setInspectorMode({
+     *   type: 'customPanel',
+     *   panelId: 'my-custom-panel',
+     *   parameters: { filter: 'active' }
+     * });
+     *
+     * // Low intent mode change - won't interrupt editing with unsaved changes
+     * await ctx.setInspectorMode(
+     *   { type: 'itemList' },
+     *   { ignoreIfUnsavedChanges: true }
+     * );
+     * ```
+     */
+    setInspectorMode: (
+      mode: InspectorMode,
+      options?: SetInspectorModeOptions,
+    ) => Promise<void>;
+
+    /**
+     * Sets the data for the item list inspector mode.
+     *
+     * @example
+     *
+     * ```js
+     * // Set the item list data
+     * await ctx.setInspectorItemListData({
+     *   title: 'Related Records',
+     *   itemIds: ['item-1', 'item-2', 'item-3']
+     * });
+     *
+     * // Switch to item list mode
+     * await ctx.setInspectorMode({ type: 'itemList' });
+     * ```
+     */
+    setInspectorItemListData: (data: {
+      /** The title to show in the inspector header */
+      title: string;
+      /** Array of record IDs to display in the list */
+      itemIds: string[];
+    }) => Promise<void>;
+  }
+>;
+
+export const renderInspectorBootstrapper =
+  fullScreenRenderModeBootstrapper<RenderInspectorCtx>(
+    'renderInspector',
+    (configuration, ctx) => {
+      if (!configuration.renderInspector) {
+        return;
+      }
+
+      configuration.renderInspector(ctx.inspectorId, ctx);
+    },
+  );

package/src/hooks/renderInspectorPanel.ts

@@ -0,0 +1,38 @@
+import { ImposedSizePluginFrameCtx } from '../ctx/pluginFrame';
+import { fullScreenRenderModeBootstrapper } from '../utils';
+
+export type RenderInspectorPanelHook = {
+  /**
+   * This function will be called when an inspector needs to render a specific
+   * panel (see the `renderInspector` and `setInspectorMode` functions)
+   *
+   * @tag inspector
+   */
+  renderInspectorPanel: (panelId: string, ctx: RenderInspectorPanelCtx) => void;
+};
+
+export type RenderInspectorPanelCtx = ImposedSizePluginFrameCtx<
+  'renderInspectorPanel',
+  {
+    /** The ID of the inspector panel that needs to be rendered */
+    panelId: string;
+
+    /**
+     * The arbitrary `parameters` of the modal declared in the `setInspectorMode`
+     * function
+     */
+    parameters: Record<string, unknown>;
+  }
+>;
+
+export const renderInspectorPanelBootstrapper =
+  fullScreenRenderModeBootstrapper<RenderInspectorPanelCtx>(
+    'renderInspectorPanel',
+    (configuration, ctx) => {
+      if (!configuration.renderInspectorPanel) {
+        return;
+      }
+
+      configuration.renderInspectorPanel(ctx.panelId, ctx);
+    },
+  );

package/src/hooks/renderPage.ts

@@ -17,6 +17,13 @@ export type RenderPageCtx = ImposedSizePluginFrameCtx<
   {
     /** The ID of the page that needs to be rendered */
     pageId: string;
+
+    /** Current page location */
+    location: {
+      pathname: string;
+      search: string;
+      hash: string;
+    };
   }
 >;
 

package/src/hooks/schemaItemTypeDropdownActions.ts

@@ -0,0 +1,22 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { Ctx } from '../ctx/base';
+import { DropdownAction, DropdownActionGroup } from '../shared';
+
+type ItemType = SchemaTypes.ItemType;
+
+export type SchemaItemTypeDropdownActionsHook = {
+  /**
+   * Use this function to define custom actions (or groups of actions) for a model/block model in the Schema section.
+   *
+   * The `executeSchemaItemTypeDropdownAction()` hook will be triggered once the user
+   * clicks on one of the defined actions.
+   *
+   * @tag dropdownActions
+   */
+  schemaItemTypeDropdownActions: (
+    itemType: ItemType,
+    ctx: SchemaItemTypeDropdownActionsCtx,
+  ) => Array<DropdownAction | DropdownActionGroup>;
+};
+
+export type SchemaItemTypeDropdownActionsCtx = Ctx;

package/src/icon.ts

@@ -1,19 +1,90 @@
-import { isRecord, isString } from './guardUtils.js';
+import { isEmoji, isRecord, isString } from './guardUtils.js';
 
-export type Icon =
-  | AwesomeFontIconIdentifier
-  | { type: 'svg'; viewBox: string; content: string };
+export type Icon = AwesomeFontIconIdentifier | SvgDefinition | EmojiDefinition;
 
 export function isIcon(value: unknown): value is Icon {
+  return isString(value) || isSvgDefinition(value) || isEmojiDefinition(value);
+}
+
+/**
+ * Defines a custom SVG icon for use in DatoCMS plugins.
+ *
+ * To create an SVG definition from an existing SVG file:
+ * 1. Grab the `viewBox` attribute from your SVG element (e.g., "0 0 24 24")
+ * 2. Grab everything between the `<svg>` tags as the content (all the paths, circles, etc.)
+ *
+ * @example
+ * ```typescript
+ * // From this SVG:
+ * // <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+ * //   <path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/>
+ * // </svg>
+ *
+ * const starIcon: SvgDefinition = {
+ *   type: 'svg',
+ *   viewBox: '0 0 24 24',
+ *   content: '<path d="M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z"/>'
+ * };
+ * ```
+ */
+export type SvgDefinition = {
+  /** Always set to 'svg' to indicate this is a custom SVG icon */
+  type: 'svg';
+
+  /**
+   * The viewBox attribute from your SVG element (e.g., "0 0 24 24").
+   * This defines the coordinate system and aspect ratio of the SVG.
+   */
+  viewBox: string;
+
+  /**
+   * The inner content of your SVG element — everything between the opening and closing <svg> tags.
+   * This includes all paths, circles, rectangles, and other SVG elements that make up your icon.
+   */
+  content: string;
+};
+
+export function isSvgDefinition(value: unknown): value is SvgDefinition {
   return (
-    isString(value) ||
-    (isRecord(value) &&
-      value.type === 'svg' &&
-      isString(value.viewBox) &&
-      isString(value.content))
+    isRecord(value) &&
+    value.type === 'svg' &&
+    isString(value.viewBox) &&
+    isString(value.content)
   );
 }
 
+/**
+ * Defines an emoji icon for use in DatoCMS plugins.
+ *
+ * @example
+ * ```typescript
+ * const starIcon: EmojiDefinition = {
+ *   type: 'emoji',
+ *   emoji: '⭐'
+ * };
+ * ```
+ */
+export type EmojiDefinition = {
+  /** Always set to 'emoji' to indicate this is an emoji icon */
+  type: 'emoji';
+
+  /**
+   * A string contaning a single emoji.
+   */
+  emoji: string;
+};
+
+export function isEmojiDefinition(value: unknown): value is EmojiDefinition {
+  return isRecord(value) && value.type === 'emoji' && isEmoji(value.emoji);
+}
+
+/**
+ * Font Awesome icon identifier for use in DatoCMS plugins.
+ *
+ * Use Font Awesome icons for consistent visual styling across the admin interface.
+ * This is the recommended approach for most plugin icons, with custom SVGs reserved
+ * primarily for brand/company logos where Font Awesome doesn't have an appropriate match.
+ */
 export type AwesomeFontIconIdentifier =
   | '0'
   | '00'

package/src/index.ts

@@ -25,6 +25,7 @@ export * from './hooks/customMarksForStructuredTextField';
 export * from './hooks/executeFieldDropdownAction';
 export * from './hooks/executeItemFormDropdownAction';
 export * from './hooks/executeItemsDropdownAction';
+export * from './hooks/executeSchemaItemTypeDropdownAction';
 export * from './hooks/executeUploadsDropdownAction';
 export * from './hooks/fieldDropdownActions';
 export * from './hooks/initialLocationQueryForItemSelector';
@@ -52,8 +53,11 @@ export * from './hooks/renderItemFormSidebarPanel';
 export * from './hooks/renderManualFieldExtensionConfigScreen';
 export * from './hooks/renderModal';
 export * from './hooks/renderPage';
+export * from './hooks/renderInspector';
+export * from './hooks/renderInspectorPanel';
 export * from './hooks/renderUploadSidebar';
 export * from './hooks/renderUploadSidebarPanel';
+export * from './hooks/schemaItemTypeDropdownActions';
 export * from './hooks/settingsAreaSidebarItemGroups';
 export * from './hooks/uploadsDropdownActions';
 export * from './hooks/uploadSidebarPanels';