@daisychainapp/maily-to-core 0.0.24 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daisychainapp/maily-to-core",
-  "version": "0.0.24",
+  "version": "0.1.2",
   "description": "Powerful editor for creating beautiful, pre-designed, mobile-ready emails.",
   "private": false,
   "main": "./dist/index.js",
@@ -20,6 +20,11 @@
       "browser": "./dist/blocks/index.mjs",
       "import": "./dist/blocks/index.mjs",
       "require": "./dist/blocks/index.js"
+    },
+    "./extensions": {
+      "browser": "./dist/extensions/index.mjs",
+      "import": "./dist/extensions/index.mjs",
+      "require": "./dist/extensions/index.js"
     }
   },
   "typesVersions": {
@@ -29,6 +34,9 @@
       ],
       "blocks": [
         "dist/blocks/index.d.ts"
+      ],
+      "extensions": [
+        "dist/extensions/index.d.ts"
       ]
     }
   },
@@ -60,6 +68,7 @@
     "@radix-ui/react-slot": "^1.1.0",
     "@radix-ui/react-tooltip": "^1.1.3",
     "@tiptap/core": "^2.9.1",
+    "@tiptap/extension-code-block-lowlight": "^2.11.5",
     "@tiptap/extension-color": "^2.9.1",
     "@tiptap/extension-document": "^2.9.1",
     "@tiptap/extension-dropcursor": "^2.9.1",
@@ -81,6 +90,8 @@
     "@tiptap/suggestion": "^2.9.1",
     "clsx": "^2.1.1",
     "fast-deep-equal": "^3.1.3",
+    "highlight.js": "^11.11.1",
+    "lowlight": "^3.3.0",
     "lucide-react": "^0.453.0",
     "react-colorful": "^5.6.1",
     "tailwind-merge": "^2.5.4",

package/readme.md

@@ -47,18 +47,95 @@ function App(props: AppProps) {
 
 ### 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.
+Slash commands let you interact with the editor by typing `/` followed by a command name. Commands are now organized into groups. Each group is an object with a `title` and a `commands` array. Every command within that array is a `BlockItem` that can either be a single command or a grouped command (with commands).
+
+#### Basic Example
+
+Suppose you have a couple of basic blocks, such as a text block or a heading block. You would organize them into a group like this:
 
 ```tsx
-// (Omitted repeated imports)
+// omitting imports
 import { text, heading1 } from '@maily-to/core/blocks';
 
 <Editor
-  blocks={[text, heading1]}
+  blocks={[
+    {
+      title: 'Basic Blocks',
+      commands: [text, heading1],
+    },
+  ]}
+/>
+```
+
+> **Note:** The order of the groups and the order of commands within each group determine how they are displayed in the editor.
+
+#### Grouped Command Blocks with Subcommands
+
+Sometimes, you may want a single command to open a list of commands. For this, define a command with an `id` and a `commands` array. The `id` is used for the slash command query (for example, typing `/headers.` will show its subcommands).
+
+```tsx
+// omitting imports
+<Editor
+  blocks={[
+    {
+      title: 'Formatting',
+      commands: [
+        {
+          title: 'Headers',
+          // The id is used to filter commands; e.g. `/headers.` shows these subcommands.
+          id: 'headers',
+          searchTerms: ['header', 'title'],
+          commands: [
+            {
+              title: 'Heading 1',
+              searchTerms: ['h1', 'heading1'],
+              command: ({ editor, range }) => {
+                // Convert the current block to Heading 1.
+              },
+            },
+            {
+              title: 'Heading 2',
+              searchTerms: ['h2', 'heading2'],
+              command: ({ editor, range }) => {
+                // Convert the current block to Heading 2.
+              },
+            },
+            // Add more subcommands as needed.
+          ],
+        },
+      ],
+    },
+  ]}
 />
 ```
 
-> Note: The order of the blocks matters. It will be shown in the order you provide.
+In this setup, when the user types `/headers.`, the editor will display the available header subcommands.
+
+> **Note:** Currently it only supports one level of depth for subcommands.
+
+#### Custom Rendered Blocks
+
+To render a custom block, you can pass a `render` function to the block object. The `render` function will receive the editor instance as an argument. You can return `null` if you don't want to render anything based on the editor's state.
+
+```tsx
+// omitting imports
+<Editor
+  blocks={[
+    {
+      title: 'Custom Blocks',
+      commands: [
+        {
+          title: 'Custom Block',
+          searchTerms: ['custom'],
+          render: (editor) => {
+            return <div>Custom Block</div>;
+          },
+        },
+      ],
+    },
+  ]}
+/>
+```
 
 ### Variables
 
@@ -94,10 +171,10 @@ You can pass variables to the editor in two ways:
      variables={({ query, from, editor }) => {
        // magic goes here
        // query: the text after the trigger character
-       // from: the context from where the variables are requested (for, variable)
+       // from: the context from where the variables are requested (repeat, variable)
        // editor: the editor instance
-       if (from === 'for') {
-         // return variables for the For block `each` key
+       if (from === 'repeat-variable') {
+         // return variables for the Repeat block `each` key
          return [
            { name: 'notifications' },
            { name: 'comments' },
@@ -114,6 +191,57 @@ You can pass variables to the editor in two ways:
 
 > 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.
 
+### 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.
+
+```tsx
+// (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:
+
+```tsx
+// (Omitted repeated imports)
+import { CustomExtension } from './extensions/custom-extension';
+
+<Editor
+  extensions={[
+    CustomExtension.configure({
+      // your configuration
+    }),
+  ]}
+/>
+```
+
 See the [@maily-to/render](../render) package for more information on how to render the editor content to HTML.
 
 ## License