datocms-plugin-sdk 2.1.0-alpha.1 → 2.1.0

package/manifest.json

@@ -1139,6 +1139,140 @@
         "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"
+              },
+              "highlightedItemId": {
+                "comment": {
+                  "markdownText": "The ID of the record the currently is highlighted by the user."
+                },
+                "location": {
+                  "filePath": "src/hooks/renderInspector.ts",
+                  "lineNumber": 83
+                },
+                "type": "string | undefined"
+              },
+              "location": {
+                "comment": {
+                  "markdownText": "Current page location."
+                },
+                "location": {
+                  "filePath": "src/hooks/renderInspector.ts",
+                  "lineNumber": 86
+                },
+                "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": 136
+                },
+                "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": 157
+                },
+                "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": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datocms-plugin-sdk",
-  "version": "2.1.0-alpha.1",
+  "version": "2.1.0",
   "description": "DatoCMS Plugin SDK",
   "keywords": [
     "datocms",
@@ -36,14 +36,15 @@
     "url": "https://github.com/datocms/plugins-sdk/issues"
   },
   "dependencies": {
-    "@datocms/cma-client": "^5.2.0-alpha.1",
+    "@datocms/cma-client": "*",
     "@types/react": "^17.0.3",
     "datocms-structured-text-utils": "^2.0.0",
+    "emoji-regex-xs": "*",
     "penpal": "^4.1.1"
   },
   "devDependencies": {
     "glob": "^11.0.0",
     "typescript": "^5.6.2"
   },
-  "gitHead": "423f893f8f19b054ae769e2dff1787342f866fab"
+  "gitHead": "42fea5d307d19f45233586a41f3aad273f58a577"
 }

package/src/connect.ts

@@ -37,6 +37,14 @@ import {
   RenderFieldExtensionHook,
   renderFieldExtensionBootstrapper,
 } from './hooks/renderFieldExtension';
+import {
+  RenderInspectorHook,
+  renderInspectorBootstrapper,
+} from './hooks/renderInspector';
+import {
+  RenderInspectorPanelHook,
+  renderInspectorPanelBootstrapper,
+} from './hooks/renderInspectorPanel';
 import {
   RenderItemCollectionOutletHook,
   renderItemCollectionOutletBootstrapper,
@@ -117,6 +125,8 @@ export type FullConnectParameters = AssetSourcesHook &
   RenderManualFieldExtensionConfigScreenHook &
   RenderModalHook &
   RenderPageHook &
+  RenderInspectorHook &
+  RenderInspectorPanelHook &
   RenderUploadSidebarHook &
   RenderUploadSidebarPanelHook &
   SchemaItemTypeDropdownActionsHook &
@@ -264,6 +274,8 @@ export async function connect(
       renderManualFieldExtensionConfigScreenBootstrapper,
     renderModal: renderModalBootstrapper,
     renderPage: renderPageBootstrapper,
+    renderInspector: renderInspectorBootstrapper,
+    renderInspectorPanel: renderInspectorPanelBootstrapper,
     renderUploadSidebar: renderUploadSidebarBootstrapper,
     renderUploadSidebarPanel: renderUploadSidebarPanelBootstrapper,
   };

package/src/guardUtils.ts

@@ -1,3 +1,7 @@
+import emojiRegex from 'emoji-regex-xs';
+
+export type Emoji = string & { readonly __brand: 'Emoji' };
+
 export function isNullish(value: unknown): value is null | undefined {
   return value === null || value === undefined;
 }
@@ -10,6 +14,15 @@ export function isString(value: unknown): value is string {
   return typeof value === 'string';
 }
 
+export function isEmoji(value: unknown): value is Emoji {
+  if (!isString(value)) return false;
+
+  const regex = emojiRegex();
+  const match = value.match(regex);
+
+  return match !== null && match.length === 1 && match[0] === value;
+}
+
 export function isNumber(value: unknown): value is number {
   return typeof value === 'number';
 }

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/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/icon.ts

@@ -1,6 +1,10 @@
-import { isRecord, isString } from './guardUtils.js';
+import { isEmoji, isRecord, isString } from './guardUtils.js';
 
-export type Icon = AwesomeFontIconIdentifier | SvgDefinition;
+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.
@@ -40,16 +44,40 @@ export type SvgDefinition = {
   content: string;
 };
 
-export function isIcon(value: unknown): value is Icon {
+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.
  *

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';