datocms-plugin-sdk 2.0.4 → 2.0.5

package/src/hooks/manualFieldExtensions.ts

@@ -1,4 +1,12 @@
 import { Ctx } from '../ctx/base';
+import {
+  isArray,
+  isBoolean,
+  isNullish,
+  isNumber,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
 
 export type ManualFieldExtensionsHook = {
   /**
@@ -14,6 +22,12 @@ export type ManualFieldExtensionsHook = {
 
 export type ManualFieldExtensionsCtx = Ctx;
 
+/**
+ * An object expressing a field extension that users will be able
+ * to install manually in some field
+ *
+ * @see {isManualFieldExtension}
+ */
 export type ManualFieldExtension = {
   /**
    * ID of field extension. Will be the first argument for the
@@ -80,3 +94,31 @@ export type FieldType =
   | 'structured_text'
   | 'text'
   | 'video';
+
+/**
+ * Checks if the provided value is a ManualFieldExtension.
+ * @param value - The value to check.
+ * @returns True if the value is a ManualFieldExtension, otherwise false.
+ */
+export function isManualFieldExtension(
+  value: unknown,
+): value is ManualFieldExtension {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    isString(value.name) &&
+    isString(value.type) &&
+    ['editor', 'addon'].includes(value.type) &&
+    (isNullish(value.asSidebarPanel) ||
+      isBoolean(value.asSidebarPanel) ||
+      (isRecord(value.asSidebarPanel) &&
+        isBoolean(value.asSidebarPanel.startOpen))) &&
+    ((isString(value.fieldTypes) && value.fieldTypes === 'all') ||
+      isArray(value.fieldTypes, isString)) &&
+    (isNullish(value.configurable) ||
+      isBoolean(value.configurable) ||
+      (isRecord(value.configurable) &&
+        isNumber(value.configurable.initialHeight))) &&
+    (isNullish(value.initialHeight) || isNumber(value.initialHeight))
+  );
+}

package/src/hooks/overrideFieldExtensions.ts

@@ -1,5 +1,14 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
+import {
+  isArray,
+  isBoolean,
+  isNullish,
+  isNumber,
+  isPlacement,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
 import { ItemFormSidebarPanelPlacement } from '../shared';
 
 type Field = SchemaTypes.Field;
@@ -25,6 +34,8 @@ export type OverrideFieldExtensionsCtx = Ctx<{
 /**
  * An object expressing some field extensions you want to force on a particular
  * field
+ *
+ * @see {isFieldExtensionOverride}
  */
 export type FieldExtensionOverride = {
   /** Force a field editor/sidebar extension on a field */
@@ -93,3 +104,56 @@ export type AddonOverride = {
    */
   initialHeight?: number;
 };
+
+/**
+ * Checks if the value is a FieldExtensionOverride.
+ * @param value The value to check.
+ * @returns True if the value is a FieldExtensionOverride, false otherwise.
+ */
+export function isFieldExtensionOverride(
+  value: unknown,
+): value is FieldExtensionOverride {
+  return (
+    isNullish(value) ||
+    (isRecord(value) &&
+      (isNullish(value.editor) || isEditorOverride(value.editor)) &&
+      (isNullish(value.addons) || isArray(value.addons, isAddonOverride)))
+  );
+}
+
+/**
+ * Checks if the value is an EditorOverride.
+ * @param value The value to check.
+ * @returns True if the value is an EditorOverride, false otherwise.
+ */
+export function isEditorOverride(value: unknown): value is EditorOverride {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    (isNullish(value.asSidebarPanel) ||
+      isBoolean(value.asSidebarPanel) ||
+      (isRecord(value.asSidebarPanel) &&
+        (isNullish(value.asSidebarPanel.startOpen) ||
+          isBoolean(value.asSidebarPanel.startOpen)) &&
+        (isNullish(value.asSidebarPanel.placement) ||
+          isPlacement(value.asSidebarPanel.placement)))) &&
+    (isNullish(value.parameters) || isRecord(value.parameters)) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.initialHeight) || isNumber(value.initialHeight))
+  );
+}
+
+/**
+ * Checks if the value is an AddonOverride.
+ * @param value The value to check.
+ * @returns True if the value is an AddonOverride, false otherwise.
+ */
+export function isAddonOverride(value: unknown): value is AddonOverride {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    (isNullish(value.parameters) || isRecord(value.parameters)) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.initialHeight) || isNumber(value.initialHeight))
+  );
+}

package/src/hooks/uploadSidebarPanels.ts

@@ -1,4 +1,12 @@
 import { Ctx } from '../ctx/base';
+import {
+  isBoolean,
+  isNullish,
+  isNumber,
+  isPlacement,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
 
 export type UploadSidebarPanelsHook = {
   /**
@@ -12,6 +20,12 @@ export type UploadSidebarPanelsHook = {
 
 export type UploadSidebarPanelsCtx = Ctx;
 
+/**
+ * An object expressing a sidebar panel to be shown when the user
+ * opens up an asset in the Media Area
+ *
+ * @see {isUploadSidebarPanel}
+ */
 export type UploadSidebarPanel = {
   /**
    * ID of the panel. Will be the first argument for the
@@ -57,3 +71,23 @@ export type UploadSidebarPanelPlacement = [
     | 'replace'
   ),
 ];
+
+/**
+ * Type guard for UploadSidebarPanel
+ * @param value - The value to check
+ * @returns True if the value is an UploadSidebarPanel
+ */
+export function isUploadSidebarPanel(
+  value: unknown,
+): value is UploadSidebarPanel {
+  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/uploadSidebars.ts

@@ -1,4 +1,5 @@
 import { Ctx } from '../ctx/base';
+import { isNullish, isNumber, isRecord, isString } from '../guardUtils.js';
 
 export type UploadSidebarsHook = {
   /**
@@ -12,6 +13,12 @@ export type UploadSidebarsHook = {
 
 export type UploadSidebarsCtx = Ctx;
 
+/**
+ * An object expressing a sidebar to be shown when the user opens
+ * up an asset in the Media Area
+ *
+ * @see {isUploadSidebar}
+ */
 export type UploadSidebar = {
   /**
    * ID of the sidebar. Will be the first argument for the
@@ -36,3 +43,19 @@ export type UploadSidebar = {
   /** The preferred width for the sidebar */
   preferredWidth?: number;
 };
+
+/**
+ * Checks if the provided value is an UploadSidebar.
+ * @param value - The value to check.
+ * @returns True if the value is an UploadSidebar, otherwise false.
+ */
+export function isUploadSidebar(value: unknown): value is UploadSidebar {
+  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/icon.ts

@@ -1,7 +1,19 @@
+import { isRecord, isString } from './guardUtils.js';
+
 export type Icon =
   | AwesomeFontIconIdentifier
   | { type: 'svg'; viewBox: string; content: string };
 
+export function isIcon(value: unknown): value is Icon {
+  return (
+    isString(value) ||
+    (isRecord(value) &&
+      value.type === 'svg' &&
+      isString(value.viewBox) &&
+      isString(value.content))
+  );
+}
+
 export type AwesomeFontIconIdentifier =
   | '0'
   | '00'

package/src/manifest.ts

@@ -60,7 +60,7 @@ export const manifest: Manifest = {
       returnType: 'UploadSidebar[]',
       location: {
         filePath: 'src/hooks/uploadSidebars.ts',
-        lineNumber: 10,
+        lineNumber: 11,
       },
     },
     uploadSidebarPanels: {
@@ -79,7 +79,7 @@ export const manifest: Manifest = {
       returnType: 'UploadSidebarPanel[]',
       location: {
         filePath: 'src/hooks/uploadSidebarPanels.ts',
-        lineNumber: 10,
+        lineNumber: 18,
       },
     },
     settingsAreaSidebarItemGroups: {
@@ -1601,7 +1601,7 @@ export const manifest: Manifest = {
               itemType: {
                 location: {
                   filePath: 'src/hooks/overrideFieldExtensions.ts',
-                  lineNumber: 22,
+                  lineNumber: 31,
                 },
                 type: 'ItemType',
               },
@@ -1613,7 +1613,7 @@ export const manifest: Manifest = {
       returnType: 'FieldExtensionOverride | undefined',
       location: {
         filePath: 'src/hooks/overrideFieldExtensions.ts',
-        lineNumber: 15,
+        lineNumber: 24,
       },
     },
     onBoot: {
@@ -1747,7 +1747,7 @@ export const manifest: Manifest = {
       returnType: 'ManualFieldExtension[]',
       location: {
         filePath: 'src/hooks/manualFieldExtensions.ts',
-        lineNumber: 10,
+        lineNumber: 18,
       },
     },
     mainNavigationTabs: {
@@ -1766,7 +1766,7 @@ export const manifest: Manifest = {
       returnType: 'MainNavigationTab[]',
       location: {
         filePath: 'src/hooks/mainNavigationTabs.ts',
-        lineNumber: 11,
+        lineNumber: 18,
       },
     },
     itemsDropdownActions: {
@@ -1826,7 +1826,7 @@ export const manifest: Manifest = {
       returnType: 'ItemFormSidebar[]',
       location: {
         filePath: 'src/hooks/itemFormSidebars.ts',
-        lineNumber: 13,
+        lineNumber: 14,
       },
     },
     itemFormSidebarPanels: {
@@ -1850,7 +1850,7 @@ export const manifest: Manifest = {
       returnType: 'ItemFormSidebarPanel[]',
       location: {
         filePath: 'src/hooks/itemFormSidebarPanels.ts',
-        lineNumber: 14,
+        lineNumber: 22,
       },
     },
     itemFormOutlets: {
@@ -1874,7 +1874,7 @@ export const manifest: Manifest = {
       returnType: 'ItemFormOutlet[]',
       location: {
         filePath: 'src/hooks/itemFormOutlets.ts',
-        lineNumber: 13,
+        lineNumber: 14,
       },
     },
     itemFormDropdownActions: {
@@ -2017,7 +2017,7 @@ export const manifest: Manifest = {
       returnType: 'ItemCollectionOutlet[]',
       location: {
         filePath: 'src/hooks/itemCollectionOutlets.ts',
-        lineNumber: 13,
+        lineNumber: 14,
       },
     },
     initialLocationQueryForItemSelector: {
@@ -2851,7 +2851,7 @@ export const manifest: Manifest = {
               itemType: {
                 location: {
                   filePath: 'src/hooks/customMarksForStructuredTextField.ts',
-                  lineNumber: 22,
+                  lineNumber: 29,
                 },
                 type: 'ItemType',
               },
@@ -2863,7 +2863,7 @@ export const manifest: Manifest = {
       returnType: 'StructuredTextCustomMark[] | undefined',
       location: {
         filePath: 'src/hooks/customMarksForStructuredTextField.ts',
-        lineNumber: 15,
+        lineNumber: 22,
       },
     },
     customBlockStylesForStructuredTextField: {
@@ -2888,7 +2888,7 @@ export const manifest: Manifest = {
                 location: {
                   filePath:
                     'src/hooks/customBlockStylesForStructuredTextField.ts',
-                  lineNumber: 22,
+                  lineNumber: 23,
                 },
                 type: 'ItemType',
               },
@@ -2900,7 +2900,7 @@ export const manifest: Manifest = {
       returnType: 'StructuredTextCustomBlockStyle[] | undefined',
       location: {
         filePath: 'src/hooks/customBlockStylesForStructuredTextField.ts',
-        lineNumber: 15,
+        lineNumber: 16,
       },
     },
     contentAreaSidebarItems: {
@@ -2919,7 +2919,7 @@ export const manifest: Manifest = {
       returnType: 'ContentAreaSidebarItem[]',
       location: {
         filePath: 'src/hooks/contentAreaSidebarItems.ts',
-        lineNumber: 10,
+        lineNumber: 17,
       },
     },
     buildItemPresentationInfo: {
@@ -2943,7 +2943,7 @@ export const manifest: Manifest = {
       returnType: 'MaybePromise<ItemPresentationInfo | undefined>',
       location: {
         filePath: 'src/hooks/buildItemPresentationInfo.ts',
-        lineNumber: 14,
+        lineNumber: 15,
       },
     },
     assetSources: {
@@ -2962,7 +2962,7 @@ export const manifest: Manifest = {
       returnType: 'AssetSource[] | undefined',
       location: {
         filePath: 'src/hooks/assetSources.ts',
-        lineNumber: 11,
+        lineNumber: 12,
       },
     },
   },

package/src/shared.ts

@@ -1,5 +1,18 @@
-import { Icon } from './icon';
+import {
+  isArray,
+  isBoolean,
+  isNullish,
+  isNumber,
+  isRecord,
+  isString,
+} from './guardUtils.js';
+import { Icon, isIcon } from './icon';
 
+/**
+ * An object expressing a dropdown action to be shown in the interface
+ *
+ * @see {isDropdownAction}
+ */
 export type DropdownAction = {
   /**
    * ID of action. Will be the first argument for the
@@ -38,6 +51,11 @@ export type DropdownAction = {
   rank?: number;
 };
 
+/**
+ * An object expressing a dropdown submenu containing actions to be shown in the interface
+ *
+ * @see {isDropdownActionGroup}
+ */
 export type DropdownActionGroup = {
   /** Label to be shown. Must be unique. */
   label: string;
@@ -65,3 +83,32 @@ export type ItemFormSidebarPanelPlacement = [
   'before' | 'after',
   'info' | 'publishedVersion' | 'schedule' | 'links' | 'history',
 ];
+
+export function isDropdownAction(value: unknown): value is DropdownAction {
+  if (!isRecord(value)) return false;
+
+  return (
+    isString(value.id) &&
+    (isNullish(value.parameters) || isRecord(value.parameters)) &&
+    isString(value.label) &&
+    isIcon(value.icon) &&
+    (isNullish(value.active) || isBoolean(value.active)) &&
+    (isNullish(value.alert) || isBoolean(value.alert)) &&
+    (isNullish(value.disabled) || isBoolean(value.disabled)) &&
+    (isNullish(value.closeMenuOnClick) || isBoolean(value.closeMenuOnClick)) &&
+    (isNullish(value.rank) || isNumber(value.rank))
+  );
+}
+
+export function isDropdownActionGroup(
+  value: unknown,
+): value is DropdownActionGroup {
+  if (!isRecord(value)) return false;
+
+  return (
+    isString(value.label) &&
+    isIcon(value.icon) &&
+    isArray(value.actions, isDropdownAction) &&
+    (isNullish(value.rank) || isNumber(value.rank))
+  );
+}