datocms-plugin-sdk 0.3.30 → 0.3.34-alpha.1

package/src/types.ts

@@ -1,10 +1,19 @@
+import {
+  BlockquoteType,
+  CodeType,
+  HeadingType,
+  ListType,
+  ParagraphType,
+  ThematicBreakType,
+} from 'datocms-structured-text-utils';
+
 import {
   Account,
   Field,
+  Fieldset,
   Item,
   ModelBlock,
   Plugin,
-  PluginAttributes,
   Role,
   Site,
   SsoUser,
@@ -42,7 +51,7 @@ export type MainNavigationTab = {
    * 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! *
+   * clash with the one of another plugin!
    */
   rank?: number;
 };
@@ -138,6 +147,27 @@ export type ContentAreaSidebarItem = {
 
 export type FieldExtensionType = 'editor' | 'addon';
 
+export type FieldType =
+  | 'boolean'
+  | 'color'
+  | 'date_time'
+  | 'date'
+  | 'file'
+  | 'float'
+  | 'gallery'
+  | 'integer'
+  | 'json'
+  | 'lat_lon'
+  | 'link'
+  | 'links'
+  | 'rich_text'
+  | 'seo'
+  | 'slug'
+  | 'string'
+  | 'structured_text'
+  | 'text'
+  | 'video';
+
 /**
  * Field extensions extend the basic functionality of DatoCMS when it comes to
  * presenting record's fields to the final user. Depending on the extension type
@@ -163,8 +193,11 @@ export type ManualFieldExtension = {
    * editing page, mimicking a sidebar panel
    */
   asSidebarPanel?: boolean | { startOpen: boolean };
-  /** The type of fields that the field extension in compatible with */
-  fieldTypes: NonNullable<PluginAttributes['field_types']> | 'all';
+  /**
+   * The type of fields that the field extension in compatible with. You can use
+   * the shortcut `all` to target all types of fields
+   */
+  fieldTypes: 'all' | FieldType[];
   /**
    * Whether this field extension needs some configuration options before being
    * installed in a field or not. Will trigger the
@@ -267,6 +300,74 @@ export type AddonOverride = {
   initialHeight?: number;
 };
 
+export type StructuredTextCustomMarkPlacement = [
+  'before' | 'after',
+  'strong' | 'emphasis' | 'underline' | 'code' | 'highlight' | 'strikethrough',
+];
+
+/** An object expressing a custom mark for a Structured Text field */
+export type StructuredTextCustomMark = {
+  /** ID of mark */
+  id: string;
+  /** Label representing the custom mark */
+  label: string;
+  toolbarButton: {
+    /**
+     * 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;
+    /**
+     * Expresses where you want the custom mark button to be placed inside the
+     * toolbar. If not specified, the item will be placed after the standard
+     * marks provided by DatoCMS itself.
+     */
+    placement?: StructuredTextCustomMarkPlacement;
+    /**
+     * If multiple custom marks specify the same `placement` for their toolbar
+     * button, they will be sorted 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;
+  };
+  /**
+   * Keyboard shortcut associated with the custom mark, expressed using the
+   * https://github.com/ianstormtaylor/is-hotkey syntax (ie. `mod+shift+x`)
+   */
+  keyboardShortcut?: string;
+  /** How the custom mark will be styled inside the editor */
+  appliedStyle: React.CSSProperties;
+};
+
+/** An object expressing a custom block style for a Structured Text field */
+export type StructuredTextCustomBlockStyle = {
+  /** ID of custom block style */
+  id: string;
+  /** The block node that can apply this style */
+  node:
+    | ParagraphType
+    | HeadingType
+    | ListType
+    | BlockquoteType
+    | CodeType
+    | ThematicBreakType;
+  /** ID of custom block style */
+  label: string;
+  /** How the block will be styled inside the editor to represent the style */
+  appliedStyle: React.CSSProperties;
+  /**
+   * Custom styles for a block node will be sorted 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;
+};
+
 /** An object expressing some field extensions you want to force on a particular field */
 export type FieldExtensionOverride = {
   /** Force a field editor/sidebar extension on a field */
@@ -460,6 +561,14 @@ export type RenderAdditionalProperties = {
    * to load them.
    */
   fields: Partial<Record<string, Field>>;
+  /**
+   * All the fieldsets currently loaded for the current DatoCMS project, indexed
+   * by ID. It will always contain the current model fields and all the fields
+   * of the blocks it might contain via Modular Content/Structured Text fields.
+   * If some fields you need are not present, use the `loadItemTypeFieldsets`
+   * function to load them.
+   */
+  fieldsets: Partial<Record<string, Fieldset>>;
   /** An object containing the theme colors for the current DatoCMS project */
   theme: Theme;
   /**
@@ -613,6 +722,25 @@ export type LoadDataMethods = {
    * ```
    */
   loadItemTypeFields: (itemTypeId: string) => Promise<Field[]>;
+  /**
+   * Loads all the fieldsets for a specific model (or block). Fieldsets will be
+   * returned and will also be available in the the `fieldsets` property.
+   *
+   * @example
+   *
+   * ```js
+   * const itemTypeId = prompt('Please insert a model ID:');
+   *
+   * const fieldsets = await ctx.loadItemTypeFieldsets(itemTypeId);
+   *
+   * ctx.notice(
+   *   `Success! ${fieldsets
+   *     .map((fieldset) => fieldset.attributes.title)
+   *     .join(', ')}`,
+   * );
+   * ```
+   */
+  loadItemTypeFieldsets: (itemTypeId: string) => Promise<Fieldset[]>;
   /**
    * Loads all the fields in the project that are currently using the plugin for
    * one of its manual field extensions.