datocms-plugin-sdk 1.1.1 → 2.0.1

package/src/manifestTypes.ts

@@ -0,0 +1,153 @@
+/**
+ * Type representing a manifest.
+ */
+export type Manifest = {
+  /**
+   * Hooks and their respective information.
+   */
+  hooks: Record<string, HookInfo>;
+  /**
+   * Base properties and methods available on every context argument.
+   */
+  baseCtx: {
+    /**
+     * Properties in the base context.
+     */
+    properties: AdditionalPropertiesOrMethodsGroup[];
+    /**
+     * Methods in the base context.
+     */
+    methods: AdditionalPropertiesOrMethodsGroup[];
+  };
+  /**
+   * Extra properties and methods available on every SelfResizingPluginFrameCtx context argument
+   */
+  selfResizingPluginFrameCtxSizingUtilities: AdditionalPropertiesOrMethodsGroup;
+};
+
+/**
+ * Type representing hook information.
+ */
+export type HookInfo = {
+  /**
+   * Name of the hook.
+   */
+  name: string;
+  /**
+   * JSDoc comment and tag for the hook.
+   */
+  comment?: Comment;
+  /**
+   * Non-context arguments for the hook.
+   */
+  nonCtxArguments: NonCtxArgument[];
+  /**
+   * Context argument for the hook, if any.
+   */
+  ctxArgument?: CtxArgument;
+  /**
+   * Return type of the hook function.
+   */
+  returnType: string;
+  /**
+   * Code location where the hook is defined.
+   */
+  location: CodeLocation;
+};
+
+/**
+ * Type representing a code location.
+ */
+export type CodeLocation = {
+  /**
+   * File path where the code is defined.
+   */
+  filePath: string;
+  /**
+   * Line number in the file where the hook is defined.
+   */
+  lineNumber: number;
+};
+
+/**
+ * Type alias for additional parameters or methods in context.
+ */
+export type AdditionalPropertyOrMethod = {
+  /**
+   * Description of the parameter or method.
+   */
+  comment?: Comment;
+  /**
+   * Code location where the parameter or method is defined.
+   */
+  location: CodeLocation;
+  /**
+   * Type of the parameter or method.
+   */
+  type: string;
+};
+
+export type AdditionalPropertiesOrMethodsGroup = {
+  /**
+   * Name of the group
+   */
+  name?: string;
+  /**
+   * Description of the group
+   */
+  comment?: Comment;
+  /**
+   * Type of the parameter or method.
+   */
+  items: Record<string, AdditionalPropertyOrMethod>;
+};
+
+/**
+ * Type alias for the context argument extracted from hook type.
+ */
+export type CtxArgument = {
+  /**
+   * Type of the context argument.
+   */
+  type: string;
+  /**
+   * Additional properties in the context argument, if any.
+   */
+  additionalProperties?: AdditionalPropertiesOrMethodsGroup[];
+  /**
+   * Additional methods in the context argument, if any.
+   */
+  additionalMethods?: AdditionalPropertiesOrMethodsGroup[];
+};
+
+/**
+ * Type alias for non-context arguments.
+ */
+export type NonCtxArgument = {
+  /**
+   * Name of the non-context argument.
+   */
+  name: string;
+  /**
+   * Type name of the non-context argument.
+   */
+  typeName: string;
+};
+
+/**
+ * Type representing a comment.
+ */
+export type Comment = {
+  /**
+   * The comment itself.
+   */
+  comment: string;
+  /**
+   * JSDoc tag for the comment, if any.
+   */
+  tag?: string;
+  /**
+   * Example or example code for the comment, if any.
+   */
+  example?: string;
+};

package/src/shared.ts

@@ -0,0 +1,67 @@
+import { Icon } from './icon';
+
+export type DropdownAction = {
+  /**
+   * ID of action. Will be the first argument for the
+   * execute function
+   */
+  id: string;
+
+  /**
+   * An arbitrary configuration object that will be passed as the `parameters`
+   * property of the second argument of the execute function
+   */
+  parameters?: Record<string, unknown>;
+
+  /** Label to be shown. Must be unique. */
+  label: string;
+
+  /**
+   * Icon to be shown alongside the label. Can be a FontAwesome icon name (ie.
+   * `"address-book"`) or a custom SVG definition. To maintain visual
+   * consistency with the rest of the interface, try to use FontAwesome icons
+   * whenever possible.
+   */
+  icon: Icon;
+
+  active?: boolean;
+  alert?: boolean;
+  disabled?: boolean;
+  closeMenuOnClick?: boolean;
+
+  /**
+   * Actions will be displayed by ascending `rank`. If you want to specify an
+   * explicit value for `rank`, make sure to offer a way for final users to
+   * customize it inside the plugin's settings form, otherwise the hardcoded
+   * value you choose might clash with the one of another plugin!
+   */
+  rank?: number;
+};
+
+export type DropdownActionGroup = {
+  /** Label to be shown. Must be unique. */
+  label: string;
+
+  /**
+   * Icon to be shown alongside the label. Can be a FontAwesome icon name (ie.
+   * `"address-book"`) or a custom SVG definition. To maintain visual
+   * consistency with the rest of the interface, try to use FontAwesome icons
+   * whenever possible.
+   */
+  icon: Icon;
+
+  actions: DropdownAction[];
+
+  /**
+   * Actions will be displayed by ascending `rank`. If you want to specify an
+   * explicit value for `rank`, make sure to offer a way for final users to
+   * customize it inside the plugin's settings form, otherwise the hardcoded
+   * value you choose might clash with the one of another plugin!
+   */
+  rank?: number;
+};
+
+export type ItemFormSidebarPanelPlacement = [
+  'before' | 'after',
+  'info' | 'publishedVersion' | 'schedule' | 'links' | 'history',
+];

package/src/utils.ts

@@ -0,0 +1,253 @@
+import type { SchemaTypes } from '@datocms/cma-client';
+import { FullConnectParameters } from './connect';
+import { Ctx } from './ctx/base';
+import { SizingUtilities } from './ctx/commonExtras/sizing';
+import {
+  ImposedSizePluginFrameCtx,
+  SelfResizingPluginFrameCtx,
+} from './ctx/pluginFrame';
+
+type Field = SchemaTypes.Field;
+type ItemType = SchemaTypes.ItemType;
+
+export type AwaitedReturnType<T extends (...args: any) => any> = Awaited<
+  ReturnType<T>
+>;
+
+type ModeForPluginFrameCtx<T> = T extends ImposedSizePluginFrameCtx<
+  infer Mode,
+  any,
+  any
+>
+  ? Mode
+  : never;
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export function pick<T extends object, K extends keyof T>(
+  obj: T,
+  keys: readonly K[],
+): Pick<T, K> {
+  const result = {} as Pick<T, K>;
+  for (const key of keys) {
+    if (key in obj) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}
+
+export function omit<T extends object, K extends keyof T>(
+  obj: T,
+  keys: readonly K[],
+): Omit<T, K> {
+  const result = { ...obj } as T;
+  for (const key of keys) {
+    delete result[key];
+  }
+  return result as Omit<T, K>;
+}
+
+export function fromOneFieldIntoMultipleAndResultsById<Result>(
+  fn:
+    | ((
+        field: Field,
+        ctx: Ctx<any, any> & {
+          itemType: ItemType;
+        },
+      ) => Result)
+    | undefined,
+) {
+  return (
+    fields: Field[],
+    ctx: Ctx<any, any>,
+  ): Record<string, Result> | undefined => {
+    if (!fn) {
+      return undefined;
+    }
+
+    const result: Record<string, Result> = {};
+
+    for (const field of fields) {
+      const itemType = ctx.itemTypes[
+        field.relationships.item_type.data.id
+      ] as ItemType;
+      result[field.id] = fn(field, { ...ctx, itemType });
+    }
+
+    return result;
+  };
+}
+
+export type Methods = {
+  getSettings: () => Promise<Properties>;
+};
+
+export type Properties<Mode extends string = string> = { mode: Mode };
+
+type OnChangeListenerFn = (newSettings: any) => void;
+
+export type ExtractRenderHooks<T extends Record<string, unknown>> = {
+  [K in keyof T as K extends `render${string}` ? K : never]: T[K];
+};
+
+export type Bootstrapper<
+  H extends keyof ExtractRenderHooks<FullConnectParameters>,
+> = {
+  (
+    connectConfiguration: Partial<ExtractRenderHooks<FullConnectParameters>>,
+    methods: Methods,
+    initialProperties: Properties,
+  ): undefined | OnChangeListenerFn;
+  mode: H;
+};
+
+export function containedRenderModeBootstrapper<
+  Ctx extends SelfResizingPluginFrameCtx<any, {}, {}>,
+>(
+  mode: ModeForPluginFrameCtx<Ctx>,
+  callConfigurationMethod: (
+    connectConfiguration: Partial<ExtractRenderHooks<FullConnectParameters>>,
+    ctx: Ctx,
+  ) => void,
+): Bootstrapper<Ctx['mode']> {
+  const bootstrapper: Bootstrapper<Ctx['mode']> = (
+    connectConfiguration,
+    methods,
+    initialProperties,
+  ) => {
+    if (initialProperties.mode !== mode) {
+      return undefined;
+    }
+
+    const sizingUtilities = buildSizingUtilities(methods);
+
+    const render = (properties: Record<string, unknown>) => {
+      callConfigurationMethod(connectConfiguration, {
+        ...methods,
+        ...properties,
+        ...sizingUtilities,
+      } as unknown as Ctx);
+    };
+
+    render(initialProperties);
+
+    return render;
+  };
+
+  bootstrapper.mode = mode;
+
+  return bootstrapper;
+}
+
+export function fullScreenRenderModeBootstrapper<
+  Ctx extends ImposedSizePluginFrameCtx<any, {}, {}>,
+>(
+  mode: ModeForPluginFrameCtx<Ctx>,
+  callConfigurationMethod: (
+    connectConfiguration: Partial<ExtractRenderHooks<FullConnectParameters>>,
+    ctx: Ctx,
+  ) => void,
+): Bootstrapper<Ctx['mode']> {
+  const bootstrapper: Bootstrapper<Ctx['mode']> = (
+    connectConfiguration,
+    methods,
+    initialProperties,
+  ) => {
+    if (initialProperties.mode !== mode) {
+      return undefined;
+    }
+
+    const render = (properties: Record<string, unknown>) => {
+      callConfigurationMethod(connectConfiguration, {
+        ...methods,
+        ...properties,
+      } as unknown as Ctx);
+    };
+
+    render(initialProperties);
+
+    return render;
+  };
+
+  bootstrapper.mode = mode;
+
+  return bootstrapper;
+}
+
+function getMaxScrollHeight() {
+  const elements = document.querySelectorAll('body *');
+  let maxVal = 0;
+  for (let i = 0; i < elements.length; i++) {
+    maxVal = Math.max(elements[i].getBoundingClientRect().bottom, maxVal);
+  }
+  return maxVal;
+}
+
+const buildSizingUtilities = (
+  methods: SelfResizingPluginFrameCtx<any, any, any>,
+): SizingUtilities => {
+  let oldHeight: null | number = null;
+
+  const updateHeight = (height?: number) => {
+    const realHeight =
+      height === undefined
+        ? Math.max(
+            document.body.scrollHeight,
+            document.body.offsetHeight,
+            document.documentElement.getBoundingClientRect().height,
+            getMaxScrollHeight(),
+          )
+        : height;
+
+    if (realHeight !== oldHeight) {
+      methods.setHeight(realHeight);
+      oldHeight = realHeight;
+    }
+  };
+
+  let resizeObserver: ResizeObserver | null = null;
+  let mutationObserver: MutationObserver | null = null;
+  const onMutation = () => updateHeight();
+
+  const startAutoResizer = () => {
+    updateHeight();
+
+    if (!resizeObserver) {
+      resizeObserver = new ResizeObserver(onMutation);
+      resizeObserver.observe(document.documentElement);
+    }
+
+    if (!mutationObserver) {
+      mutationObserver = new MutationObserver(onMutation);
+
+      mutationObserver.observe(window.document.body, {
+        attributes: true,
+        childList: true,
+        subtree: true,
+        characterData: true,
+      });
+    }
+  };
+
+  const stopAutoResizer = () => {
+    if (resizeObserver) {
+      resizeObserver.disconnect();
+      resizeObserver = null;
+    }
+
+    if (mutationObserver) {
+      mutationObserver.disconnect();
+      mutationObserver = null;
+    }
+  };
+
+  const isAutoResizerActive = () => Boolean(resizeObserver);
+
+  return {
+    updateHeight,
+    startAutoResizer,
+    stopAutoResizer,
+    isAutoResizerActive,
+  };
+};

package/dist/cjs/guards.js

@@ -1,19 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isRenderAssetSourceParent = exports.isRenderManualFieldExtensionConfigScreenParent = exports.isRenderFieldExtensionParent = exports.isRenderItemFormOutletParent = exports.isRenderSidebarParent = exports.isRenderSidebarPanelParent = exports.isRenderModalParent = exports.isRenderConfigScreenParent = exports.isRenderPageParent = exports.isOnBootParent = void 0;
-function buildGuard(mode) {
-    return function (parent, settings) {
-        return settings.mode === mode;
-    };
-}
-exports.isOnBootParent = buildGuard('onBoot');
-exports.isRenderPageParent = buildGuard('renderPage');
-exports.isRenderConfigScreenParent = buildGuard('renderConfigScreen');
-exports.isRenderModalParent = buildGuard('renderModal');
-exports.isRenderSidebarPanelParent = buildGuard('renderItemFormSidebarPanel');
-exports.isRenderSidebarParent = buildGuard('renderItemFormSidebar');
-exports.isRenderItemFormOutletParent = buildGuard('renderItemFormOutlet');
-exports.isRenderFieldExtensionParent = buildGuard('renderFieldExtension');
-exports.isRenderManualFieldExtensionConfigScreenParent = buildGuard('renderManualFieldExtensionConfigScreen');
-exports.isRenderAssetSourceParent = buildGuard('renderAssetSource');
-//# sourceMappingURL=guards.js.map

package/dist/cjs/guards.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/guards.ts"],"names":[],"mappings":";;;AAeA,SAAS,UAAU,CAAmB,IAAY;IAChD,OAAO,UAAC,MAAc,EAAE,QAA0B;QAChD,OAAA,QAAQ,CAAC,IAAI,KAAK,IAAI;IAAtB,CAAsB,CAAC;AAC3B,CAAC;AAEY,QAAA,cAAc,GAAG,UAAU,CAAgB,QAAQ,CAAC,CAAC;AAErD,QAAA,kBAAkB,GAAG,UAAU,CAAoB,YAAY,CAAC,CAAC;AAEjE,QAAA,0BAA0B,GACrC,UAAU,CAA4B,oBAAoB,CAAC,CAAC;AAEjD,QAAA,mBAAmB,GAC9B,UAAU,CAAqB,aAAa,CAAC,CAAC;AAEnC,QAAA,0BAA0B,GAAG,UAAU,CAClD,4BAA4B,CAC7B,CAAC;AAEW,QAAA,qBAAqB,GAAG,UAAU,CAC7C,uBAAuB,CACxB,CAAC;AAEW,QAAA,4BAA4B,GACvC,UAAU,CAA8B,sBAAsB,CAAC,CAAC;AAErD,QAAA,4BAA4B,GACvC,UAAU,CAA8B,sBAAsB,CAAC,CAAC;AAErD,QAAA,8CAA8C,GACzD,UAAU,CACR,wCAAwC,CACzC,CAAC;AAES,QAAA,yBAAyB,GACpC,UAAU,CAA2B,mBAAmB,CAAC,CAAC"}

package/dist/cjs/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/esm/guards.d.ts

@@ -1,37 +0,0 @@
-import type { RenderItemFormOutletMethods } from '.';
-import type { OnBootMethods, RenderAssetSourceMethods, RenderConfigScreenMethods, RenderFieldExtensionMethods, RenderManualFieldExtensionConfigScreenMethods, RenderModalMethods, RenderPageMethods, RenderSidebarMethods, RenderSidebarPanelMethods } from './types';
-export declare type Parent = {
-    getSettings: () => Promise<{
-        mode: string;
-    }>;
-};
-export declare const isOnBootParent: (parent: Parent, settings: {
-    mode: string;
-}) => parent is OnBootMethods;
-export declare const isRenderPageParent: (parent: Parent, settings: {
-    mode: string;
-}) => parent is RenderPageMethods;
-export declare const isRenderConfigScreenParent: (parent: Parent, settings: {
-    mode: string;
-}) => parent is RenderConfigScreenMethods;
-export declare const isRenderModalParent: (parent: Parent, settings: {
-    mode: string;
-}) => parent is RenderModalMethods;
-export declare const isRenderSidebarPanelParent: (parent: Parent, settings: {
-    mode: string;
-}) => parent is RenderSidebarPanelMethods;
-export declare const isRenderSidebarParent: (parent: Parent, settings: {
-    mode: string;
-}) => parent is RenderSidebarMethods;
-export declare const isRenderItemFormOutletParent: (parent: Parent, settings: {
-    mode: string;
-}) => parent is RenderItemFormOutletMethods;
-export declare const isRenderFieldExtensionParent: (parent: Parent, settings: {
-    mode: string;
-}) => parent is RenderFieldExtensionMethods;
-export declare const isRenderManualFieldExtensionConfigScreenParent: (parent: Parent, settings: {
-    mode: string;
-}) => parent is RenderManualFieldExtensionConfigScreenMethods;
-export declare const isRenderAssetSourceParent: (parent: Parent, settings: {
-    mode: string;
-}) => parent is RenderAssetSourceMethods;

package/dist/esm/guards.js

@@ -1,16 +0,0 @@
-function buildGuard(mode) {
-    return function (parent, settings) {
-        return settings.mode === mode;
-    };
-}
-export var isOnBootParent = buildGuard('onBoot');
-export var isRenderPageParent = buildGuard('renderPage');
-export var isRenderConfigScreenParent = buildGuard('renderConfigScreen');
-export var isRenderModalParent = buildGuard('renderModal');
-export var isRenderSidebarPanelParent = buildGuard('renderItemFormSidebarPanel');
-export var isRenderSidebarParent = buildGuard('renderItemFormSidebar');
-export var isRenderItemFormOutletParent = buildGuard('renderItemFormOutlet');
-export var isRenderFieldExtensionParent = buildGuard('renderFieldExtension');
-export var isRenderManualFieldExtensionConfigScreenParent = buildGuard('renderManualFieldExtensionConfigScreen');
-export var isRenderAssetSourceParent = buildGuard('renderAssetSource');
-//# sourceMappingURL=guards.js.map

package/dist/esm/guards.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/guards.ts"],"names":[],"mappings":"AAeA,SAAS,UAAU,CAAmB,IAAY;IAChD,OAAO,UAAC,MAAc,EAAE,QAA0B;QAChD,OAAA,QAAQ,CAAC,IAAI,KAAK,IAAI;IAAtB,CAAsB,CAAC;AAC3B,CAAC;AAED,MAAM,CAAC,IAAM,cAAc,GAAG,UAAU,CAAgB,QAAQ,CAAC,CAAC;AAElE,MAAM,CAAC,IAAM,kBAAkB,GAAG,UAAU,CAAoB,YAAY,CAAC,CAAC;AAE9E,MAAM,CAAC,IAAM,0BAA0B,GACrC,UAAU,CAA4B,oBAAoB,CAAC,CAAC;AAE9D,MAAM,CAAC,IAAM,mBAAmB,GAC9B,UAAU,CAAqB,aAAa,CAAC,CAAC;AAEhD,MAAM,CAAC,IAAM,0BAA0B,GAAG,UAAU,CAClD,4BAA4B,CAC7B,CAAC;AAEF,MAAM,CAAC,IAAM,qBAAqB,GAAG,UAAU,CAC7C,uBAAuB,CACxB,CAAC;AAEF,MAAM,CAAC,IAAM,4BAA4B,GACvC,UAAU,CAA8B,sBAAsB,CAAC,CAAC;AAElE,MAAM,CAAC,IAAM,4BAA4B,GACvC,UAAU,CAA8B,sBAAsB,CAAC,CAAC;AAElE,MAAM,CAAC,IAAM,8CAA8C,GACzD,UAAU,CACR,wCAAwC,CACzC,CAAC;AAEJ,MAAM,CAAC,IAAM,yBAAyB,GACpC,UAAU,CAA2B,mBAAmB,CAAC,CAAC"}