datocms-plugin-sdk 0.3.10 → 0.3.24-alpha.3

package/dist/types/connect.d.ts

@@ -1,17 +1,18 @@
 import { Field, ModelBlock } from './SiteApiSchema';
-import { ContentAreaSidebarItem, FieldExtensionOverride, InitPropertiesAndMethods, ItemFormSidebarPanel, MainNavigationTab, ManualFieldExtension, OnBootPropertiesAndMethods, RenderConfigScreenPropertiesAndMethods, RenderFieldExtensionPropertiesAndMethods, RenderManualFieldExtensionConfigScreenPropertiesAndMethods, RenderModalPropertiesAndMethods, RenderPagePropertiesAndMethods, RenderSidebarPanePropertiesAndMethods, SettingsAreaSidebarItemGroup } from './types';
+import { AssetSource, ContentAreaSidebarItem, FieldExtensionOverride, InitPropertiesAndMethods, ItemFormSidebarPanel, MainNavigationTab, ManualFieldExtension, OnBootPropertiesAndMethods, RenderAssetSourcePropertiesAndMethods, RenderConfigScreenPropertiesAndMethods, RenderFieldExtensionPropertiesAndMethods, RenderManualFieldExtensionConfigScreenPropertiesAndMethods, RenderModalPropertiesAndMethods, RenderPagePropertiesAndMethods, RenderSidebarPanePropertiesAndMethods, SettingsAreaSidebarItemGroup } from './types';
 export declare type SizingUtilities = {
     /**
-     * Listens for DOM changes and automatically calls `setHeight` when it detects a change.
-     * If you're using `datocms-react-ui` package, the `<Canvas />` component already takes
-     * care of calling this method for you.
+     * Listens for DOM changes and automatically calls `setHeight` when it detects
+     * a change. If you're using `datocms-react-ui` package, the `<Canvas />`
+     * component already takes care of calling this method for you.
      */
     startAutoResizer: () => void;
     /** Stops resizing the iframe automatically */
     stopAutoResizer: () => void;
     /**
-     * Triggers a change in the size of the iframe. If you don't explicitely pass a
-     * `newHeight` it will be automatically calculated using the iframe content at the moment
+     * Triggers a change in the size of the iframe. If you don't explicitely pass
+     * a `newHeight` it will be automatically calculated using the iframe content
+     * at the moment
      */
     updateHeight: (newHeight?: number) => void;
 };
@@ -23,6 +24,7 @@ export declare type FieldIntentCtx = InitPropertiesAndMethods & {
 };
 export declare type RenderPageCtx = RenderPagePropertiesAndMethods;
 export declare type RenderModalCtx = RenderModalPropertiesAndMethods & SizingUtilities;
+export declare type RenderAssetSourceCtx = RenderAssetSourcePropertiesAndMethods & SizingUtilities;
 export declare type RenderItemFormSidebarPanelCtx = RenderSidebarPanePropertiesAndMethods & SizingUtilities;
 export declare type RenderFieldExtensionCtx = RenderFieldExtensionPropertiesAndMethods & SizingUtilities;
 export declare type RenderManualFieldExtensionConfigScreenCtx = RenderManualFieldExtensionConfigScreenPropertiesAndMethods & SizingUtilities;
@@ -30,8 +32,8 @@ export declare type RenderConfigScreenCtx = RenderConfigScreenPropertiesAndMetho
 /** The full options you can pass to the `connect` function */
 export declare type FullConnectParameters = {
     /**
-     * This function will be called once at boot time and can be used to perform ie. some
-     * initial integrity checks on the configuration.
+     * This function will be called once at boot time and can be used to perform
+     * ie. some initial integrity checks on the configuration.
      *
      * @group boot
      */
@@ -55,69 +57,86 @@ export declare type FullConnectParameters = {
      */
     contentAreaSidebarItems: (ctx: IntentCtx) => ContentAreaSidebarItem[];
     /**
-     * Use this function to declare new field extensions that users will be able to install
-     * manually in some field
+     * Use this function to declare new field extensions that users will be able
+     * to install manually in some field
      *
      * @group manualFieldExtensions
      */
     manualFieldExtensions: (ctx: IntentCtx) => ManualFieldExtension[];
     /**
-     * Use this function to declare new sidebar panels to be shown when the user edits
-     * records of a particular model
+     * Use this function to declare additional sources to be shown when users want
+     * to upload new assets
+     *
+     * @group assetSources
+     */
+    assetSources: (ctx: IntentCtx) => AssetSource[] | void;
+    /**
+     * Use this function to declare new sidebar panels to be shown when the user
+     * edits records of a particular model
      *
      * @group sidebarPanels
      */
     itemFormSidebarPanels: (itemType: ModelBlock, ctx: IntentCtx) => ItemFormSidebarPanel[];
     /**
-     * Use this function to automatically force one or more field extensions to a particular field
+     * Use this function to automatically force one or more field extensions to a
+     * particular field
      *
      * @group forcedFieldExtensions
      */
     overrideFieldExtensions: (field: Field, ctx: FieldIntentCtx) => FieldExtensionOverride | void;
     /**
-     * This function will be called when the plugin needs to render the plugin's configuration form
+     * This function will be called when the plugin needs to render the plugin's
+     * configuration form
      *
      * @group configScreen
      */
     renderConfigScreen: (ctx: RenderConfigScreenCtx) => void;
     /**
-     * This function will be called when the plugin needs to render a specific page (see the
-     * `mainNavigationTabs`, `settingsAreaSidebarItemGroups` and `contentAreaSidebarItems` functions)
+     * This function will be called when the plugin needs to render a specific
+     * page (see the `mainNavigationTabs`, `settingsAreaSidebarItemGroups` and
+     * `contentAreaSidebarItems` functions)
      *
      * @group pages
      */
     renderPage: (pageId: string, ctx: RenderPageCtx) => void;
     /**
-     * This function will be called when the plugin requested to open a modal (see the
-     * `openModal` function)
+     * This function will be called when the plugin requested to open a modal (see
+     * the `openModal` function)
      *
      * @group modals
      */
     renderModal: (modalId: string, ctx: RenderModalCtx) => void;
     /**
-     * This function will be called when the plugin needs to render a sidebar panel (see the
-     * `itemFormSidebarPanels` function)
+     * This function will be called when the plugin needs to render a sidebar
+     * panel (see the `itemFormSidebarPanels` function)
      *
      * @group sidebarPanels
      */
     renderItemFormSidebarPanel: (sidebarPaneId: string, ctx: RenderItemFormSidebarPanelCtx) => void;
     /**
-     * This function will be called when the plugin needs to render a field extension (see
-     * the `manualFieldExtensions` and `overrideFieldExtensions` functions)
+     * This function will be called when the user selects one of the plugin's
+     * asset sources to upload a new media file.
+     *
+     * @group assetSources
+     */
+    renderAssetSource: (assetSourceId: string, ctx: RenderAssetSourceCtx) => void;
+    /**
+     * This function will be called when the plugin needs to render a field
+     * extension (see the `manualFieldExtensions` and `overrideFieldExtensions` functions)
      *
      * @group forcedFieldExtensions
      */
     renderFieldExtension: (fieldExtensionId: string, ctx: RenderFieldExtensionCtx) => void;
     /**
-     * This function will be called when the plugin needs to render the configuration form
-     * for installing a field extension inside a particular field
+     * This function will be called when the plugin needs to render the
+     * configuration form for installing a field extension inside a particular field
      *
      * @group manualFieldExtensions
      */
     renderManualFieldExtensionConfigScreen: (fieldExtensionId: string, ctx: RenderManualFieldExtensionConfigScreenCtx) => void;
     /**
-     * This function will be called each time the configuration object changes. It must
-     * return an object containing possible validation errors
+     * This function will be called each time the configuration object changes. It
+     * must return an object containing possible validation errors
      *
      * @group manualFieldExtensions
      */

package/dist/types/guards.d.ts

@@ -1,4 +1,4 @@
-import { InitMethods, OnBootMethods, RenderPageMethods, RenderFieldExtensionMethods, RenderConfigScreenMethods, RenderManualFieldExtensionConfigScreenMethods, RenderSidebarPanelMethods, RenderModalMethods } from './types';
+import { InitMethods, OnBootMethods, RenderPageMethods, RenderFieldExtensionMethods, RenderConfigScreenMethods, RenderManualFieldExtensionConfigScreenMethods, RenderSidebarPanelMethods, RenderModalMethods, RenderAssetSourceMethods } from './types';
 export declare type Parent = {
     getSettings: () => Promise<{
         mode: string;
@@ -28,3 +28,6 @@ export declare const isRenderFieldExtensionParent: (parent: Parent, settings: {
 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/types/types.d.ts

@@ -1,10 +1,20 @@
-import { Account, Field, Item, ModelBlock, Plugin, PluginAttributes, Role, Site, SsoUser, Upload, User } from './SiteApiSchema';
+import { Account, Field, Item, ModelBlock, Plugin, PluginAttributes, Role, Site, SsoUser, Upload, UploadCreateSchema, User } from './SiteApiSchema';
+export declare type Icon = string | {
+    type: 'svg';
+    viewBox: string;
+    content: string;
+};
 /** A tab to be displayed in the top-bar of the UI */
 export declare type MainNavigationTab = {
     /** Label to be shown. Must be unique. */
     label: string;
-    /** FontAwesome icon name to be shown alongside the label */
-    icon: 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;
     /** ID of the page linked to the tab */
     pointsTo: {
         pageId: string;
@@ -30,8 +40,13 @@ export declare type MainNavigationTab = {
 export declare type SettingsAreaSidebarItem = {
     /** Label to be shown. Must be unique. */
     label: string;
-    /** FontAwesome icon name to be shown alongside the label */
-    icon: 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;
     /** ID of the page linked to the item */
     pointsTo: {
         pageId: string;
@@ -72,8 +87,13 @@ export declare type SettingsAreaSidebarItemGroup = {
 export declare type ContentAreaSidebarItem = {
     /** Label to be shown. Must be unique. */
     label: string;
-    /** FontAwesome icon name to be shown alongside the label */
-    icon: 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;
     /** ID of the page linked to the item */
     pointsTo: {
         pageId: string;
@@ -276,6 +296,33 @@ export declare type Modal = {
     /** The initial height to set for the iframe that will render the modal content */
     initialHeight?: number;
 };
+/** An additional asset source */
+export declare type AssetSource = {
+    /**
+     * ID of the asset source. Will be the first argument for the
+     * `renderAssetSource` function
+     */
+    id: string;
+    /** Name of the asset that will be shown to the user */
+    name: string;
+    /**
+     * Icon to be shown alongside the name. 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;
+    /**
+     * Configuration options for the modal that will be opened to select a media
+     * file from this source
+     */
+    modal?: {
+        /** Width of the modal. Can be a number, or one of the predefined sizes */
+        width?: 's' | 'm' | 'l' | 'xl' | number;
+        /** The initial height to set for the iframe that will render the modal content */
+        initialHeight?: number;
+    };
+};
 /** A toast notification to present to the user */
 export declare type Toast<CtaValue = unknown> = {
     /** Message of the notification */
@@ -1027,6 +1074,82 @@ export declare type RenderModalAdditionalMethods = {
 };
 export declare type RenderModalMethods = RenderMethods & IframeMethods & RenderModalAdditionalMethods;
 export declare type RenderModalPropertiesAndMethods = RenderModalMethods & RenderModalProperties;
+/** Information regarding the specific asset source browser that you need to render */
+export declare type RenderAssetSourceAdditionalProperties = {
+    mode: 'renderAssetSource';
+    /** The ID of the assetSource that needs to be rendered */
+    assetSourceId: string;
+};
+export declare type RenderAssetSourceProperties = RenderProperties & RenderAssetSourceAdditionalProperties;
+export declare type NewUploadResourceAsUrl = {
+    /**
+     * URL for the resource. The URL must respond with a
+     * `Access-Control-Allow-Origin` header — for instance `*`, which will allow
+     * all hosts — allowing the image to be read by DatoCMS
+     */
+    url: string;
+    /**
+     * Optional filename to be used to generate the final DatoCMS URL. If not
+     * passed, the URL will be used
+     */
+    filename?: string;
+};
+export declare type NewUploadResourceAsBase64 = {
+    /**
+     * Base64 encoded data URI for the resource.
+     *
+     * Format:
+     *
+     * `data:[<mime type>][;charset=<charset>];base64,<encoded data>`
+     */
+    base64: string;
+    /** Filename to be used to generate the final DatoCMS URL */
+    filename: string;
+};
+export declare type NewUpload = {
+    /** The actual resource that will be uploaded */
+    resource: NewUploadResourceAsUrl | NewUploadResourceAsBase64;
+    /** Copyright to apply to the asset */
+    copyright?: string;
+    /** Author to apply to the asset */
+    author?: string;
+    /** Notes to apply to the asset */
+    notes?: string;
+    /** Tags to apply to the asset */
+    tags?: string[];
+    /**
+     * An hash containing, for each locale of the project, the default metadata to
+     * apply to the asset
+     */
+    defaultFieldMetadata?: NonNullable<Record<string, UploadCreateSchema['data']['attributes']['default_field_metadata']>>;
+};
+/** Use these methods to confirm */
+export declare type RenderAssetSourceAdditionalMethods = {
+    getSettings: () => Promise<RenderAssetSourceProperties>;
+    /**
+     * Function to be called when the user selects the asset: it will trigger the
+     * creation of a new `Upload` that will be added in the Media Area.
+     *
+     * @example
+     *
+     * ```js
+     * await ctx.select({
+     *   resource: {
+     *     url:
+     *       'https://images.unsplash.com/photo-1416339306562-f3d12fefd36f',
+     *     filename: 'man-drinking-coffee.jpg',
+     *   },
+     *   copyright: 'Royalty free (Unsplash)',
+     *   author: 'Jeff Sheldon',
+     *   notes: 'A man drinking a coffee',
+     *   tags: ['man', 'coffee'],
+     * });
+     * ```
+     */
+    select: (newUpload: NewUpload) => void;
+};
+export declare type RenderAssetSourceMethods = RenderMethods & IframeMethods & RenderAssetSourceAdditionalMethods;
+export declare type RenderAssetSourcePropertiesAndMethods = RenderAssetSourceMethods & RenderAssetSourceProperties;
 /** Information regarding the specific page that you need to render */
 export declare type RenderPageAdditionalProperties = {
     mode: 'renderPage';
@@ -1039,6 +1162,20 @@ export declare type RenderPageAdditionalMethods = {
 };
 export declare type RenderPageMethods = RenderMethods & RenderPageAdditionalMethods;
 export declare type RenderPagePropertiesAndMethods = RenderPageMethods & RenderPageProperties;
+export declare type PendingField = {
+    id?: string;
+    type: 'field';
+    attributes: {
+        api_key: Field['attributes']['api_key'];
+        appearance: Field['attributes']['appearance'];
+        default_value: Field['attributes']['default_value'];
+        field_type: Field['attributes']['field_type'];
+        hint: Field['attributes']['hint'];
+        label: Field['attributes']['label'];
+        localized: Field['attributes']['localized'];
+        validators: Field['attributes']['validators'];
+    };
+};
 /**
  * Information regarding the specific form that you need to render to let the
  * end-user edit the configuration object of a field extension
@@ -1057,6 +1194,10 @@ export declare type RenderManualFieldExtensionConfigScreenAdditionalProperties =
      * implementing the `validateManualFieldExtensionParameters` function)
      */
     errors: Record<string, unknown>;
+    /** The field entity that is being edited in the form */
+    pendingField: PendingField;
+    /** The model for the field being edited */
+    itemType: ModelBlock;
 };
 export declare type RenderManualFieldExtensionConfigScreenProperties = RenderProperties & RenderManualFieldExtensionConfigScreenAdditionalProperties;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datocms-plugin-sdk",
-  "version": "0.3.10",
+  "version": "0.3.24-alpha.3",
   "description": "DatoCMS Plugin SDK",
   "keywords": [
     "datocms",
@@ -41,5 +41,5 @@
   "devDependencies": {
     "typedoc": "^0.22.8"
   },
-  "gitHead": "73616f8cbc087607c38281529f64eb849e718139"
+  "gitHead": "e0d3595cc0a4b048f5f10fbd65a5b8aa3be13936"
 }