datocms-plugin-sdk 2.0.4 → 2.0.5

package/manifest.json

@@ -55,7 +55,7 @@
       "returnType": "UploadSidebar[]",
       "location": {
         "filePath": "src/hooks/uploadSidebars.ts",
-        "lineNumber": 10
+        "lineNumber": 11
       }
     },
     "uploadSidebarPanels": {
@@ -73,7 +73,7 @@
       "returnType": "UploadSidebarPanel[]",
       "location": {
         "filePath": "src/hooks/uploadSidebarPanels.ts",
-        "lineNumber": 10
+        "lineNumber": 18
       }
     },
     "settingsAreaSidebarItemGroups": {
@@ -1478,7 +1478,7 @@
               "itemType": {
                 "location": {
                   "filePath": "src/hooks/overrideFieldExtensions.ts",
-                  "lineNumber": 22
+                  "lineNumber": 31
                 },
                 "type": "ItemType"
               }
@@ -1490,7 +1490,7 @@
       "returnType": "FieldExtensionOverride | undefined",
       "location": {
         "filePath": "src/hooks/overrideFieldExtensions.ts",
-        "lineNumber": 15
+        "lineNumber": 24
       }
     },
     "onBoot": {
@@ -1618,7 +1618,7 @@
       "returnType": "ManualFieldExtension[]",
       "location": {
         "filePath": "src/hooks/manualFieldExtensions.ts",
-        "lineNumber": 10
+        "lineNumber": 18
       }
     },
     "mainNavigationTabs": {
@@ -1636,7 +1636,7 @@
       "returnType": "MainNavigationTab[]",
       "location": {
         "filePath": "src/hooks/mainNavigationTabs.ts",
-        "lineNumber": 11
+        "lineNumber": 18
       }
     },
     "itemsDropdownActions": {
@@ -1694,7 +1694,7 @@
       "returnType": "ItemFormSidebar[]",
       "location": {
         "filePath": "src/hooks/itemFormSidebars.ts",
-        "lineNumber": 13
+        "lineNumber": 14
       }
     },
     "itemFormSidebarPanels": {
@@ -1717,7 +1717,7 @@
       "returnType": "ItemFormSidebarPanel[]",
       "location": {
         "filePath": "src/hooks/itemFormSidebarPanels.ts",
-        "lineNumber": 14
+        "lineNumber": 22
       }
     },
     "itemFormOutlets": {
@@ -1740,7 +1740,7 @@
       "returnType": "ItemFormOutlet[]",
       "location": {
         "filePath": "src/hooks/itemFormOutlets.ts",
-        "lineNumber": 13
+        "lineNumber": 14
       }
     },
     "itemFormDropdownActions": {
@@ -1875,7 +1875,7 @@
       "returnType": "ItemCollectionOutlet[]",
       "location": {
         "filePath": "src/hooks/itemCollectionOutlets.ts",
-        "lineNumber": 13
+        "lineNumber": 14
       }
     },
     "initialLocationQueryForItemSelector": {
@@ -2649,7 +2649,7 @@
               "itemType": {
                 "location": {
                   "filePath": "src/hooks/customMarksForStructuredTextField.ts",
-                  "lineNumber": 22
+                  "lineNumber": 29
                 },
                 "type": "ItemType"
               }
@@ -2661,7 +2661,7 @@
       "returnType": "StructuredTextCustomMark[] | undefined",
       "location": {
         "filePath": "src/hooks/customMarksForStructuredTextField.ts",
-        "lineNumber": 15
+        "lineNumber": 22
       }
     },
     "customBlockStylesForStructuredTextField": {
@@ -2684,7 +2684,7 @@
               "itemType": {
                 "location": {
                   "filePath": "src/hooks/customBlockStylesForStructuredTextField.ts",
-                  "lineNumber": 22
+                  "lineNumber": 23
                 },
                 "type": "ItemType"
               }
@@ -2696,7 +2696,7 @@
       "returnType": "StructuredTextCustomBlockStyle[] | undefined",
       "location": {
         "filePath": "src/hooks/customBlockStylesForStructuredTextField.ts",
-        "lineNumber": 15
+        "lineNumber": 16
       }
     },
     "contentAreaSidebarItems": {
@@ -2714,7 +2714,7 @@
       "returnType": "ContentAreaSidebarItem[]",
       "location": {
         "filePath": "src/hooks/contentAreaSidebarItems.ts",
-        "lineNumber": 10
+        "lineNumber": 17
       }
     },
     "buildItemPresentationInfo": {
@@ -2737,7 +2737,7 @@
       "returnType": "MaybePromise<ItemPresentationInfo | undefined>",
       "location": {
         "filePath": "src/hooks/buildItemPresentationInfo.ts",
-        "lineNumber": 14
+        "lineNumber": 15
       }
     },
     "assetSources": {
@@ -2755,7 +2755,7 @@
       "returnType": "AssetSource[] | undefined",
       "location": {
         "filePath": "src/hooks/assetSources.ts",
-        "lineNumber": 11
+        "lineNumber": 12
       }
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datocms-plugin-sdk",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "DatoCMS Plugin SDK",
   "keywords": [
     "datocms",
@@ -45,5 +45,5 @@
     "glob": "^11.0.0",
     "typescript": "^5.6.2"
   },
-  "gitHead": "c08f8ec853327a4d0910217284d9406febd42b3e"
+  "gitHead": "3691996abdcc5da84a982b31db38154a7540b17f"
 }

package/src/guardUtils.ts

@@ -0,0 +1,34 @@
+export function isNullish(value: unknown): value is null | undefined {
+  return value === null || value === undefined;
+}
+
+export function isBoolean(value: unknown): value is boolean {
+  return typeof value === 'boolean';
+}
+
+export function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+export function isNumber(value: unknown): value is number {
+  return typeof value === 'number';
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function isArray<T>(
+  value: unknown,
+  checkItem: (item: unknown) => item is T,
+): value is T[] {
+  return Array.isArray(value) && value.every(checkItem);
+}
+
+export function isPlacement(value: unknown) {
+  return (
+    isArray(value, isString) &&
+    value.length === 2 &&
+    ['before', 'after'].includes(value[0])
+  );
+}

package/src/hooks/assetSources.ts

@@ -1,5 +1,6 @@
 import { Ctx } from '../ctx/base';
-import { Icon } from '../icon';
+import { isNullish, isNumber, isRecord, isString } from '../guardUtils.js';
+import { Icon, isIcon } from '../icon';
 
 export type AssetSourcesHook = {
   /**
@@ -13,7 +14,11 @@ export type AssetSourcesHook = {
 
 export type AssetSourcesCtx = Ctx;
 
-/** An additional asset source */
+/**
+ * An object expressing an additional asset source
+ *
+ * @see {isAssetSource}
+ */
 export type AssetSource = {
   /**
    * ID of the asset source. Will be the first argument for the
@@ -43,3 +48,28 @@ export type AssetSource = {
     initialHeight?: number;
   };
 };
+
+/**
+ * Type guard for AssetSource.
+ * @param value - The value to check.
+ * @returns true if the value is an AssetSource, false otherwise.
+ */
+export function isAssetSource(value: unknown): value is AssetSource {
+  if (isNullish(value)) return false;
+  if (!isRecord(value)) return false;
+
+  const { id, name, icon, modal } = value;
+
+  return (
+    isString(id) &&
+    isString(name) &&
+    isIcon(icon) &&
+    (isNullish(modal) ||
+      (isRecord(modal) &&
+        (isNullish(modal.width) ||
+          (isString(modal.width) &&
+            ['s', 'm', 'l', 'xl'].includes(modal.width)) ||
+          isNumber(modal.width)) &&
+        (isNullish(modal.initialHeight) || isNumber(modal.initialHeight))))
+  );
+}

package/src/hooks/buildItemPresentationInfo.ts

@@ -1,5 +1,6 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
+import { isNullish, isNumber, isRecord, isString } from '../guardUtils.js';
 import type { MaybePromise } from '../utils';
 
 type Item = SchemaTypes.Item;
@@ -19,6 +20,11 @@ export type BuildItemPresentationInfoHook = {
 
 export type BuildItemPresentationInfoCtx = Ctx;
 
+/**
+ * An object expressing how a record should be presented in the interface
+ *
+ * @see {isItemPresentationInfo}
+ */
 export type ItemPresentationInfo = {
   /** The title to present the record */
   title: string;
@@ -33,3 +39,19 @@ export type ItemPresentationInfo = {
    */
   rank?: number;
 };
+
+/**
+ * Checks if the value is an ItemPresentationInfo type.
+ * @param value The value to check.
+ * @returns True if the value is an ItemPresentationInfo, false otherwise.
+ */
+export function isItemPresentationInfo(
+  value: unknown,
+): value is ItemPresentationInfo {
+  return (
+    isRecord(value) &&
+    isString(value.title) &&
+    (isNullish(value.imageUrl) || isString(value.imageUrl)) &&
+    (isNullish(value.rank) || isNumber(value.rank))
+  );
+}

package/src/hooks/contentAreaSidebarItems.ts

@@ -1,5 +1,12 @@
 import { Ctx } from '../ctx/base';
-import { Icon } from '../icon';
+import {
+  isNullish,
+  isNumber,
+  isPlacement,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
+import { Icon, isIcon } from '../icon';
 
 export type ContentAreaSidebarItemsHook = {
   /**
@@ -14,6 +21,11 @@ export type ContentAreaSidebarItemsHook = {
 
 export type ContentAreaSidebarItemsCtx = Ctx;
 
+/**
+ * An object expressing an item in the content area sidebar
+ *
+ * @see {isContentAreaSidebarItem}
+ */
 export type ContentAreaSidebarItem = {
   /** Label to be shown. Must be unique. */
   label: string;
@@ -43,3 +55,22 @@ export type ContentAreaSidebarItem = {
    */
   rank?: number;
 };
+
+/**
+ * Checks if the value is a ContentAreaSidebarItem.
+ * @param value - The value to check.
+ * @returns True if the value is a ContentAreaSidebarItem, false otherwise.
+ */
+export function isContentAreaSidebarItem(
+  value: unknown,
+): value is ContentAreaSidebarItem {
+  return (
+    isRecord(value) &&
+    isString(value.label) &&
+    isIcon(value.icon) &&
+    isRecord(value.pointsTo) &&
+    isString(value.pointsTo.pageId) &&
+    (isNullish(value.placement) || isPlacement(value.placement)) &&
+    (isNullish(value.rank) || isNumber(value.rank))
+  );
+}

package/src/hooks/customBlockStylesForStructuredTextField.ts

@@ -1,6 +1,7 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { BlockNodeTypeWithCustomStyle } from 'datocms-structured-text-utils';
 import { Ctx } from '../ctx/base';
+import { isNullish, isNumber, isRecord, isString } from '../guardUtils.js';
 
 type Field = SchemaTypes.Field;
 type ItemType = SchemaTypes.ItemType;
@@ -22,7 +23,11 @@ export type CustomBlockStylesForStructuredTextFieldCtx = Ctx<{
   itemType: ItemType;
 }>;
 
-/** An object expressing a custom block style for a Structured Text field */
+/**
+ * An object expressing a custom block style for a Structured Text field
+ *
+ * @see {isStructuredTextCustomBlockStyle}
+ */
 export type StructuredTextCustomBlockStyle = {
   /** ID of custom block style */
   id: string;
@@ -40,3 +45,20 @@ export type StructuredTextCustomBlockStyle = {
    */
   rank?: number;
 };
+
+/**
+ * Checks if the given value is a StructuredTextCustomBlockStyle.
+ * @param value - The value to check.
+ * @returns True if the value is a StructuredTextCustomBlockStyle, otherwise false.
+ */
+export function isStructuredTextCustomBlockStyle(
+  value: unknown,
+): value is StructuredTextCustomBlockStyle {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    isString(value.label) &&
+    isString(value.node) &&
+    (isNullish(value.rank) || isNumber(value.rank))
+  );
+}

package/src/hooks/customMarksForStructuredTextField.ts

@@ -1,6 +1,13 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
-import { Icon } from '../icon';
+import {
+  isNullish,
+  isNumber,
+  isPlacement,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
+import { Icon, isIcon } from '../icon';
 
 type Field = SchemaTypes.Field;
 type ItemType = SchemaTypes.ItemType;
@@ -22,7 +29,11 @@ export type CustomMarksForStructuredTextFieldCtx = Ctx<{
   itemType: ItemType;
 }>;
 
-/** An object expressing a custom mark for a Structured Text field */
+/**
+ * An object expressing a custom mark for a Structured Text field
+ *
+ * @see {isStructuredTextCustomMark}
+ */
 export type StructuredTextCustomMark = {
   /** ID of mark */
   id: string;
@@ -62,3 +73,23 @@ export type StructuredTextCustomMarkPlacement = [
   'before' | 'after',
   'strong' | 'emphasis' | 'underline' | 'code' | 'highlight' | 'strikethrough',
 ];
+
+/**
+ * Checks if the given value is a StructuredTextCustomMark.
+ * @param value The value to check.
+ * @returns True if the value is a StructuredTextCustomMark, false otherwise.
+ */
+export function isStructuredTextCustomMark(
+  value: unknown,
+): value is StructuredTextCustomMark {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    isString(value.label) &&
+    isIcon(value.icon) &&
+    (isNullish(value.placement) || isPlacement(value.placement)) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.keyboardShortcut) || isString(value.keyboardShortcut)) &&
+    isRecord(value.appliedStyle)
+  );
+}

package/src/hooks/initialLocationQueryForItemSelector.ts

@@ -1,6 +1,6 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx, ItemListLocationQuery } from '../ctx/base';
-
+import { isNullish, isNumber, isRecord } from '../guardUtils.js';
 import { MaybePromise } from '../utils';
 
 type Field = SchemaTypes.Field;
@@ -22,6 +22,11 @@ export type InitialLocationQueryForItemSelectorHook = {
 
 export type InitialLocationQueryForItemSelectorCtx = Ctx;
 
+/**
+ * An object expressing which filters should be applied to the record selector
+ *
+ * @see {isInitialLocationQueryForItemSelector}
+ */
 export type InitialLocationQueryForItemSelector = {
   locationQuery: ItemListLocationQuery;
   /**
@@ -33,3 +38,18 @@ export type InitialLocationQueryForItemSelector = {
    */
   rank?: number;
 };
+
+/**
+ * Type guard for InitialLocationQueryForItemSelector
+ * @param value - The value to check
+ * @returns True if value is of type InitialLocationQueryForItemSelector, false otherwise
+ */
+export function isInitialLocationQueryForItemSelector(
+  value: unknown,
+): value is InitialLocationQueryForItemSelector {
+  return (
+    isRecord(value) &&
+    isRecord(value.locationQuery) &&
+    (isNullish(value.rank) || isNumber(value.rank))
+  );
+}

package/src/hooks/itemCollectionOutlets.ts

@@ -1,5 +1,6 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
+import { isNullish, isNumber, isRecord, isString } from '../guardUtils.js';
 
 type ItemType = SchemaTypes.ItemType;
 
@@ -18,7 +19,11 @@ export type ItemCollectionOutletsHook = {
 
 export type ItemCollectionOutletsCtx = Ctx;
 
-/** An outlet to be shown at the top of a record's collection page */
+/**
+ * An object expressing an outlet to be shown at the top of a record's collection page
+ *
+ * @see {isItemCollectionOutlet}
+ */
 export type ItemCollectionOutlet = {
   /**
    * ID of the outlet. Will be the first argument for the `renderItemCollectionOutlet`
@@ -35,3 +40,19 @@ export type ItemCollectionOutlet = {
   /** The initial height to set for the iframe that will render the outlet */
   initialHeight?: number;
 };
+
+/**
+ * Checks if the given value is an ItemCollectionOutlet.
+ * @param value - The value to check.
+ * @returns True if the value is an ItemCollectionOutlet, false otherwise.
+ */
+export function isItemCollectionOutlet(
+  value: unknown,
+): value is ItemCollectionOutlet {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.initialHeight) || isNumber(value.initialHeight))
+  );
+}

package/src/hooks/itemFormOutlets.ts

@@ -1,5 +1,6 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
+import { isNullish, isNumber, isRecord, isString } from '../guardUtils.js';
 
 type ItemType = SchemaTypes.ItemType;
 
@@ -18,6 +19,11 @@ export type ItemFormOutletsHook = {
 
 export type ItemFormOutletsCtx = Ctx;
 
+/**
+ * An object expressing an outlet to be shown at the top of a record's editing page
+ *
+ * @see {isItemFormOutlet}
+ */
 export type ItemFormOutlet = {
   /**
    * ID of the outlet. Will be the first argument for the `renderItemFormOutlet`
@@ -34,3 +40,17 @@ export type ItemFormOutlet = {
   /** The initial height to set for the iframe that will render the outlet */
   initialHeight?: number;
 };
+
+/**
+ * Checks if the given value is an ItemFormOutlet.
+ * @param value - The value to check.
+ * @returns True if the value is an ItemFormOutlet, false otherwise.
+ */
+export function isItemFormOutlet(value: unknown): value is ItemFormOutlet {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.initialHeight) || isNumber(value.initialHeight))
+  );
+}

package/src/hooks/itemFormSidebarPanels.ts

@@ -1,5 +1,13 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
+import {
+  isBoolean,
+  isNullish,
+  isNumber,
+  isPlacement,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
 import { ItemFormSidebarPanelPlacement } from '../shared';
 
 type ItemType = SchemaTypes.ItemType;
@@ -19,6 +27,12 @@ export type ItemFormSidebarPanelsHook = {
 
 export type ItemFormSidebarPanelsCtx = Ctx;
 
+/**
+ * An object expressing a sidebar panel to be shown when the user
+ * edits records of a particular model
+ *
+ * @see {isItemFormSidebarPanel}
+ */
 export type ItemFormSidebarPanel = {
   /**
    * ID of the panel. Will be the first argument for the
@@ -52,3 +66,23 @@ export type ItemFormSidebarPanel = {
   /** The initial height to set for the iframe that will render the sidebar panel */
   initialHeight?: number;
 };
+
+/**
+ * Checks if the given value is an ItemFormSidebarPanel.
+ * @param value - The value to check.
+ * @returns True if the value is an ItemFormSidebarPanel, false otherwise.
+ */
+export function isItemFormSidebarPanel(
+  value: unknown,
+): value is ItemFormSidebarPanel {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    isString(value.label) &&
+    (isNullish(value.parameters) || isRecord(value.parameters)) &&
+    (isNullish(value.startOpen) || isBoolean(value.startOpen)) &&
+    (isNullish(value.placement) || isPlacement(value.placement)) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.initialHeight) || isNumber(value.initialHeight))
+  );
+}

package/src/hooks/itemFormSidebars.ts

@@ -1,5 +1,6 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
+import { isNullish, isNumber, isRecord, isString } from '../guardUtils.js';
 
 type ItemType = SchemaTypes.ItemType;
 
@@ -18,6 +19,12 @@ export type ItemFormSidebarsHook = {
 
 export type ItemFormSidebarsCtx = Ctx;
 
+/**
+ * An object expressing a sidebar to be shown when the user edits
+ * records of a particular model
+ *
+ * @see {isItemFormSidebar}
+ */
 export type ItemFormSidebar = {
   /**
    * ID of the sidebar. Will be the first argument for the
@@ -42,3 +49,19 @@ export type ItemFormSidebar = {
   /** The preferred width for the sidebar */
   preferredWidth?: number;
 };
+
+/**
+ * Type guard to check if the value is an ItemFormSidebar.
+ * @param value - The value to check.
+ * @returns true if the value is an ItemFormSidebar, false otherwise.
+ */
+export function isItemFormSidebar(value: unknown): value is ItemFormSidebar {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    isString(value.label) &&
+    (isNullish(value.parameters) || isRecord(value.parameters)) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.preferredWidth) || isNumber(value.preferredWidth))
+  );
+}

package/src/hooks/mainNavigationTabs.ts

@@ -1,5 +1,12 @@
 import { Ctx } from '../ctx/base';
-import { Icon } from '../icon';
+import {
+  isNullish,
+  isNumber,
+  isPlacement,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
+import { Icon, isIcon } from '../icon';
 
 export type MainNavigationTabsHook = {
   /**
@@ -13,7 +20,11 @@ export type MainNavigationTabsHook = {
 
 export type MainNavigationTabsCtx = Ctx;
 
-/** A tab to be displayed in the top-bar of the UI */
+/**
+ * An object expressing a tab to be displayed in the top-bar of the UI
+ *
+ * @see {isMainNavigationTab}
+ */
 export type MainNavigationTab = {
   /** Label to be shown. Must be unique. */
   label: string;
@@ -45,3 +56,22 @@ export type MainNavigationTab = {
    */
   rank?: number;
 };
+
+/**
+ * Checks if the given value is a MainNavigationTab.
+ * @param value The value to check.
+ * @returns True if the value is a MainNavigationTab, false otherwise.
+ */
+export function isMainNavigationTab(
+  value: unknown,
+): value is MainNavigationTab {
+  return (
+    isRecord(value) &&
+    isString(value.label) &&
+    isIcon(value.icon) &&
+    isRecord(value.pointsTo) &&
+    isString(value.pointsTo.pageId) &&
+    (isNullish(value.placement) || isPlacement(value.placement)) &&
+    (isNullish(value.rank) || isNumber(value.rank))
+  );
+}