Currently, this package is under development. You can follow the progress here.

Installation

pnpm add @maily-to/core

# for types
pnpm add -D @tiptap/core

Usage

import { useState } from 'react';
import { Editor } from '@maily-to/core';
import type { Editor as TiptapEditor, JSONContent } from '@tiptap/core';

type AppProps = {
  contentJson: JSONContent;
};

function App(props: AppProps) {
  const { contentJson: defaultContentJson } = props;
  const [editor, setEditor] = useState<TiptapEditor>();

  return (
    <Editor
      contentJson={defaultContentJson}
      onCreate={setEditor}
      onUpdate={setEditor}
    />
  );
}

Slash Commands

Slash commands are a way to interact with the editor using / followed by a command name. For example, /heading1 will convert the current paragraph to a heading 1.

// (Omitted repeated imports)
import { text, heading1 } from '@maily-to/core/blocks';

<Editor
  blocks={[text, heading1]}
/>

Note: The order of the blocks matters. It will be shown in the order you provide.

Variables

By default, variables are required. You can make them optional by setting the required property to false. When a variable is optional and not provided, a placeholder will be displayed in its place.

You can pass variables to the editor in two ways:

1. As an Array of Objects:

   For auto-suggestions of variables in the editor when you type @, pass the variables as an array of objects to the variables prop.

   // (Omitted repeated imports)
   <Editor
     variableTriggerCharacter="@"
     variables={[
       {
         name: 'currentDate',
         required: false,
       },
     ]}
   />

2. As a Function:

   If the variables are dynamic and need to be generated based on the editor's state or other inputs, you can provide a function to the variables prop.

   // (Omitted repeated imports)
   <Editor
     variableTriggerCharacter="@"
     variables={({ query, from, editor }) => {
       // magic goes here
       // query: the text after the trigger character
       // from: the context from where the variables are requested (repeat, variable)
       // editor: the editor instance
       if (from === 'repeat-variable') {
         // return variables for the Repeat block `each` key
         return [
           { name: 'notifications' },
           { name: 'comments' },
         ];
       }
   
       return [
         { name: 'currentDate' },
         { name: 'currentTime', required: false },
       ];
     }}
   />

Keep it in mind that if you pass an array of variable object Maily will take care of the filtering based on the query. But if you pass a function you have to take care of the filtering.

See the @maily-to/render package for more information on how to render the editor content to HTML.

Extensions

Extensions are a way to extend the editor's functionality. You can add custom blocks, marks, or extend the editor's functionality using extensions.

// (Omitted repeated imports)
import { MailyKit, VariableExtension, getVariableSuggestions } from '@maily-to/core/extensions';

<Editor
  extensions={[
    MailyKit.configure({
      // do disable the link card node
      linkCard: false,
    }),
    // it will extend the variable extension
    // and provide suggestions for variables
    VariableExtension.extend({
      addNodeView() {
        // now you can replace the default
        // VariableView with your custom view
        return ReactNodeViewRenderer(VariableView, {
          className: 'mly-relative mly-inline-block',
          as: 'div',
        });
      },
    }).configure({
      suggestions: getVariableSuggestions(
        variables,
        variableTriggerCharacter,
        variableListComponent, // optional custom component for variable list
      ),
    }),
  ]}
/>

Or, you can add your own custom extensions, like shown below:

// (Omitted repeated imports)
import { CustomExtension } from './extensions/custom-extension';

<Editor
  extensions={[
    CustomExtension.configure({
      // your configuration
    }),
  ]}
/>

License

MIT © Arik Chakma