datocms-plugin-sdk 2.0.13 → 2.0.16

package/src/hooks/renderInspector.ts

@@ -0,0 +1,173 @@
+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;
+
+    /** 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/icon.ts

@@ -1,8 +1,44 @@
 import { isRecord, isString } from './guardUtils.js';
 
-export type Icon =
-  | AwesomeFontIconIdentifier
-  | { type: 'svg'; viewBox: string; content: string };
+export type Icon = AwesomeFontIconIdentifier | SvgDefinition;
+
+/**
+ * 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 isIcon(value: unknown): value is Icon {
   return (
@@ -14,6 +50,13 @@ export function isIcon(value: unknown): value is Icon {
   );
 }
 
+/**
+ * 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

@@ -53,6 +53,8 @@ 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';

package/src/manifest.ts

@@ -1231,6 +1231,140 @@ export const manifest: Manifest = {
         lineNumber: 14,
       },
     },
+    renderInspectorPanel: {
+      name: 'renderInspectorPanel',
+      comment: {
+        markdownText:
+          'This function will be called when an inspector needs to render a specific\npanel (see the `renderInspector` and `setInspectorMode` functions).',
+        tag: 'inspector',
+      },
+      nonCtxArguments: [
+        {
+          name: 'panelId',
+          typeName: 'string',
+        },
+      ],
+      ctxArgument: {
+        type: 'ImposedSizePluginFrameCtx',
+        additionalProperties: [
+          {
+            items: {
+              panelId: {
+                comment: {
+                  markdownText:
+                    'The ID of the inspector panel that needs to be rendered.',
+                },
+                location: {
+                  filePath: 'src/hooks/renderInspectorPanel.ts',
+                  lineNumber: 18,
+                },
+                type: 'string',
+              },
+              parameters: {
+                comment: {
+                  markdownText:
+                    'The arbitrary `parameters` of the modal declared in the `setInspectorMode`\nfunction.',
+                },
+                location: {
+                  filePath: 'src/hooks/renderInspectorPanel.ts',
+                  lineNumber: 24,
+                },
+                type: 'Record<string, unknown>',
+              },
+            },
+          },
+        ],
+        additionalMethods: [],
+      },
+      returnType: 'void',
+      location: {
+        filePath: 'src/hooks/renderInspectorPanel.ts',
+        lineNumber: 11,
+      },
+    },
+    renderInspector: {
+      name: 'renderInspector',
+      comment: {
+        markdownText:
+          'This function will be called when the plugin needs to render a specific\ninspector. Inspectors provide a side panel interface for displaying and\ninteracting with content alongside a custom interface.',
+        tag: 'inspector',
+        example:
+          "connect({\n  renderInspector(inspectorId, ctx) {\n    render(\n      <div>\n        <h1>Inspector: {inspectorId}</h1>\n        <button onClick={() => ctx.setInspectorMode({\n          type: 'itemEditor',\n          itemId: 'some-item-id'\n        })}>\n          Show Item Editor\n        </button>\n      </div>\n    );\n  }\n});",
+      },
+      nonCtxArguments: [
+        {
+          name: 'inspectorId',
+          typeName: 'string',
+        },
+      ],
+      ctxArgument: {
+        type: 'ImposedSizePluginFrameCtx',
+        additionalProperties: [
+          {
+            items: {
+              inspectorId: {
+                comment: {
+                  markdownText:
+                    'The ID of the inspector that needs to be rendered.',
+                },
+                location: {
+                  filePath: 'src/hooks/renderInspector.ts',
+                  lineNumber: 80,
+                },
+                type: 'string',
+              },
+              location: {
+                comment: {
+                  markdownText: 'Current page location.',
+                },
+                location: {
+                  filePath: 'src/hooks/renderInspector.ts',
+                  lineNumber: 83,
+                },
+                type: '{\n      pathname: string;\n      search: string;\n      hash: string;\n    }',
+              },
+            },
+          },
+        ],
+        additionalMethods: [
+          {
+            items: {
+              setInspectorMode: {
+                comment: {
+                  markdownText:
+                    'Changes the current display mode of the inspector. This allows the plugin\nto dynamically switch between showing a record list, record editor, or custom\npanel within the inspector interface.',
+                  example:
+                    "// Switch to record editor mode\nawait ctx.setInspectorMode({\n  type: 'itemEditor',\n  itemId: 'item-123',\n  fieldPath: 'title'\n});\n\n// Switch to record list mode\nawait ctx.setInspectorMode({ type: 'itemList' });\nawait ctx.setInspectorItemListData({\n  title: 'Related Records',\n  itemIds: ['item-1', 'item-2', 'item-3']\n});\n\n// Switch to custom panel mode\nawait ctx.setInspectorMode({\n  type: 'customPanel',\n  panelId: 'my-custom-panel',\n  parameters: { filter: 'active' }\n});\n\n// Low intent mode change - won't interrupt editing with unsaved changes\nawait ctx.setInspectorMode(\n  { type: 'itemList' },\n  { ignoreIfUnsavedChanges: true }\n);",
+                },
+                location: {
+                  filePath: 'src/hooks/renderInspector.ts',
+                  lineNumber: 133,
+                },
+                type: '(\n      mode: InspectorMode,\n      options?: SetInspectorModeOptions,\n    ) => Promise<void>',
+              },
+              setInspectorItemListData: {
+                comment: {
+                  markdownText:
+                    'Sets the data for the item list inspector mode.',
+                  example:
+                    "// Set the item list data\nawait ctx.setInspectorItemListData({\n  title: 'Related Records',\n  itemIds: ['item-1', 'item-2', 'item-3']\n});\n\n// Switch to item list mode\nawait ctx.setInspectorMode({ type: 'itemList' });",
+                },
+                location: {
+                  filePath: 'src/hooks/renderInspector.ts',
+                  lineNumber: 154,
+                },
+                type: '(data: {\n      /** The title to show in the inspector header */\n      title: string;\n      /** Array of record IDs to display in the list */\n      itemIds: string[];\n    }) => Promise<void>',
+              },
+            },
+          },
+        ],
+      },
+      returnType: 'void',
+      location: {
+        filePath: 'src/hooks/renderInspector.ts',
+        lineNumber: 73,
+      },
+    },
     renderFieldExtension: {
       name: 'renderFieldExtension',
       comment: {
@@ -1745,7 +1879,7 @@ export const manifest: Manifest = {
       name: 'onBeforeItemUpsert',
       comment: {
         markdownText:
-          'This function will be called before saving a new version of a record. You\ncan 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.\n\nIf you return `false`, the record will NOT be saved. A small on-page error will say "A plugin blocked the action".\nHowever, for better UX, consider also using `ctx.alert()` to better explain to the user why their save was blocked.\n\nIf you return `true`, the save will proceed as normal.\n\nThis hook runs BEFORE serverside validation. You can use it to do your own additional validation before returning.\nClientside validations are not affected by this hook, since those occur on individual fields\' `onBlur()` events.',
         tag: 'beforeHooks',
       },
       nonCtxArguments: [
@@ -1773,7 +1907,7 @@ export const manifest: Manifest = {
                 },
                 location: {
                   filePath: 'src/hooks/onBeforeItemUpsert.ts',
-                  lineNumber: 40,
+                  lineNumber: 47,
                 },
                 type: '(path: string, locale?: string) => Promise<void>',
               },
@@ -1784,7 +1918,7 @@ export const manifest: Manifest = {
       returnType: 'MaybePromise<boolean>',
       location: {
         filePath: 'src/hooks/onBeforeItemUpsert.ts',
-        lineNumber: 15,
+        lineNumber: 22,
       },
     },
     manualFieldExtensions: {