Indent plugin

.changeset/core-minor.md

@@ -0,0 +1,22 @@
+---
+'@udecode/plate-core': minor
+---
+
+feat:
+- `PlatePlugin`
+  - new field: `overrideProps`
+    - Overrides rendered node props (shallow merge).
+    - This enables controlling the props of any node component (use cases: indent, align,...).
+    - used by `pipeRenderElement` and `pipeRenderLeaf`
+- `getRenderElement` and `getRenderLeaf`:
+  - pass the rest of the props to the component
+  - `getRenderNodeProps`:
+    - computes slate class and `nodeProps`
+- new dependency: `clsx`
+- new types:
+  - `OverrideProps`
+  - `PlatePluginEditor`
+  - `PlatePluginSerialize`
+  - `PlatePluginNode`
+  - `PlatePluginElement`
+  - `PlatePluginLeaf`

.changeset/funny-onions-work.md

@@ -0,0 +1,5 @@
+---
+'@udecode/plate': minor
+---
+
+new package: plate-indent

.changeset/indent-minor.md

@@ -0,0 +1,5 @@
+---
+'@udecode/plate-indent': minor
+---
+
+new package

.changeset/real-lies-hug.md

@@ -0,0 +1,15 @@
+---
+'@udecode/plate-block-quote-ui': minor
+'@udecode/plate-code-block-ui': minor
+'@udecode/plate-excalidraw': minor
+'@udecode/plate-horizontal-rule-ui': minor
+'@udecode/plate-image-ui': minor
+'@udecode/plate-link-ui': minor
+'@udecode/plate-list-ui': minor
+'@udecode/plate-media-embed-ui': minor
+'@udecode/plate-mention-ui': minor
+'@udecode/plate-table-ui': minor
+'@udecode/plate-styled-components': minor
+---
+
+pass rest of props to the root tag

.eslintignore

@@ -1 +1 @@
-/dist
+**/dist

.eslintrc.js

@@ -214,7 +214,7 @@ module.exports = {
     //   2,
     //   { allowTernary: true, allowShortCircuit: true },
     // ],
-    '@typescript-eslint/no-unused-vars': ['warn'],
+    '@typescript-eslint/no-unused-vars': ['warn', { ignoreRestSiblings: true }],
     '@typescript-eslint/no-useless-constructor': 'error',
     '@typescript-eslint/no-var-requires': 'off',
 

docs/docs/guides/creating-plugins.mdx

@@ -100,6 +100,11 @@ export const createReactPlugin = {
 
 - Inline element types
 
+### `overrideProps`
+
+- Overrides rendered node props (shallow merge).
+- This enables controlling the props of any node component (use cases: indent, align,...).
+
 ### `pluginKeys`
 
 - Plugin keys to support configuration.

docs/docs/playground.mdx

@@ -68,6 +68,7 @@ See [Installation](/docs/installation)
         createFontBackgroundColorPlugin(),
         createFontSizePlugin(),
         createKbdPlugin(),
+        createIndentPlugin(optionsIndentPlugin),
         createNodeIdPlugin(),
         createAutoformatPlugin(optionsAutoformat),
         createResetNodePlugin(optionsResetBlockTypePlugin),
@@ -108,6 +109,7 @@ See [Installation](/docs/installation)
         <HeadingToolbar>
           <ToolbarButtonsBasicElements />
           <ToolbarButtonsList />
+          <ToolbarButtonsIndent />
           <ToolbarButtonsBasicMarks />
           <ToolbarColorPicker
             pluginKey={MARK_COLOR}

docs/docs/plugins/indent.mdx

@@ -0,0 +1,176 @@
+---
+slug: /plugins/indent
+title: Indent
+---
+
+The block indentation feature allows you to set indentation for blocks such as paragraphs or headings.
+
+Its main purpose is to visually distinguish parts of the content.
+Block indentation is mostly useful for graphically differentiate structure elements.
+
+### Installation
+
+```bash npm2yarn
+npm install @udecode/plate-indent
+```
+
+### Usage
+
+Use the indent or outdent toolbar buttons in the editor below to control the level of indentation of the content, both for paragraph text and headers.
+
+```ts live
+() => {
+  const plugins = [
+    ...pluginsBasic,
+    createIndentPlugin({
+      types: [
+        ELEMENT_PARAGRAPH,
+        ELEMENT_H1,
+      ],
+    }),
+  ];
+
+  const ToolbarButtonsIndent = () => {
+    const editor = useStoreEditorRef(useEventEditorId('focus'));
+
+    return (
+      <>
+        <ToolbarButton
+          onMouseDown={(e) => {
+            e.preventDefault();
+            outdent(editor);
+          }}
+          icon={<FormatIndentDecrease />}
+        />
+        <ToolbarButton
+          onMouseDown={(e) => {
+            e.preventDefault();
+            indent(editor);
+          }}
+          icon={<FormatIndentIncrease />}
+        />
+      </>
+    );
+  };
+
+  return (
+    <>
+      <HeadingToolbar>
+        <ToolbarButtonsIndent />
+      </HeadingToolbar>
+      <Plate
+        id="indent"
+        plugins={plugins}
+        components={components}
+        options={options}
+        editableProps={editableProps}
+        initialValue={initialValueIndent}
+      />
+    </>
+  );
+}
+```
+
+### Options
+
+This plugin has a few configuration options that can be used to adjust the block indentation behavior.
+
+#### Using `types`
+
+By default, only the paragraph can be indented.
+
+You can use the `types` option to control which types of block can be indented.
+
+The above demo is using `types: [ELEMENT_PARAGRAPH, ELEMENT_H1]` so the heading block can also be indented.
+
+#### Using `offset` and `unit`
+
+By default, the block indentation plugin increases or decreases the current indentation by the given `offset`, using the given `unit`.
+
+The above demo is using the default configuration, which defines a `24px` indentation step.
+
+You can change that value to, for example, `3em`:
+
+```ts live
+() => {
+  const plugins = [
+    ...pluginsBasic,
+    createIndentPlugin({
+      offset: 3,
+      unit: 'em',
+    }),
+  ];
+
+  return (
+    <>
+      <HeadingToolbar>
+        <ToolbarButtonsIndent />
+      </HeadingToolbar>
+      <Plate
+        id="indent-offset"
+        plugins={plugins}
+        components={components}
+        options={options}
+        editableProps={editableProps}
+        initialValue={initialValueIndent}
+      />
+    </>
+  );
+}
+```
+
+#### Using `indentMax`
+
+You generally want to set a maximum number of indentation so the text stays readable.
+
+Using `indentMax: 5` will limit the indent to 5 levels.
+
+### Using CSS classes
+
+If you want more semantics in your content, use CSS classes instead of fixed indentation units.
+You can then adjust the indentation in the style sheets of your application.
+
+You can use the option `classNames` so the plugin will pass `className` instead of `style` prop:
+
+```ts
+createIndentPlugin({
+  classNames: [
+    'slate-indent-1',
+    'slate-indent-2',
+    'slate-indent-3',
+  ],
+}),
+```
+
+```css
+.slate-indent-1 {
+  margin-left: 10%;
+}
+
+.slate-indent-2 {
+  margin-left: 20%;
+}
+
+.slate-indent-3 {
+  margin-left: 30%;
+}
+```
+
+The last class of the array has the biggest indentation, so the above options will restrict indentation levels to 3.
+
+Note that `offset` and `unit` are ignored if `classNames` is defined.
+
+### Commands
+
+#### `indent`
+
+- Increase the indentation of the selected blocks.
+
+#### `outdent`
+
+- Decrease the indentation of the selected blocks
+
+### Source Code
+
+- [Variables](https://github.com/udecode/plate/blob/main/docs/src/live/live.tsx)
+- [packages/indent](https://github.com/udecode/plate/tree/main/packages/indent/src)

docs/docusaurus.config.js

@@ -49,6 +49,7 @@ const alias = {
   '@udecode/plate-html-serializer': 'serializers/html-serializer',
   '@udecode/plate-image': 'elements/image',
   '@udecode/plate-image-ui': 'elements/image-ui',
+  '@udecode/plate-indent': 'indent',
   '@udecode/plate-kbd': 'marks/kbd',
   '@udecode/plate-link': 'elements/link',
   '@udecode/plate-link-ui': 'elements/link-ui',

docs/package.json

@@ -51,6 +51,7 @@
     "@udecode/plate-html-serializer": "link:../packages/serializers/html-serializer",
     "@udecode/plate-image": "link:../packages/elements/image",
     "@udecode/plate-image-ui": "link:../packages/elements/image-ui",
+    "@udecode/plate-indent": "link:../packages/indent",
     "@udecode/plate-kbd": "link:../packages/marks/kbd",
     "@udecode/plate-link": "link:../packages/elements/link",
     "@udecode/plate-link-ui": "link:../packages/elements/link-ui",

docs/sidebars.js

@@ -43,6 +43,7 @@ module.exports = {
             'plugins/excalidraw',
             'plugins/horizontal-rule',
             'plugins/image',
+            'plugins/indent',
             'plugins/link',
             'plugins/list',
             'plugins/media-embed',

docs/src/live/config/Toolbars.tsx

@@ -6,6 +6,7 @@ import { CodeBlock } from '@styled-icons/boxicons-regular/CodeBlock';
 import { Highlight } from '@styled-icons/boxicons-regular/Highlight';
 import { Subscript } from '@styled-icons/foundation/Subscript';
 import { Superscript } from '@styled-icons/foundation/Superscript';
+import { FormatIndentDecrease } from '@styled-icons/material';
 import { BorderAll } from '@styled-icons/material/BorderAll';
 import { BorderBottom } from '@styled-icons/material/BorderBottom';
 import { BorderClear } from '@styled-icons/material/BorderClear';
@@ -17,6 +18,7 @@ import { FormatAlignJustify } from '@styled-icons/material/FormatAlignJustify';
 import { FormatAlignLeft } from '@styled-icons/material/FormatAlignLeft';
 import { FormatAlignRight } from '@styled-icons/material/FormatAlignRight';
 import { FormatBold } from '@styled-icons/material/FormatBold';
+import { FormatIndentIncrease } from '@styled-icons/material/FormatIndentIncrease';
 import { FormatItalic } from '@styled-icons/material/FormatItalic';
 import { FormatListBulleted } from '@styled-icons/material/FormatListBulleted';
 import { FormatListNumbered } from '@styled-icons/material/FormatListNumbered';
@@ -51,6 +53,7 @@ import {
   ELEMENT_OL,
   ELEMENT_UL,
   getPlatePluginType,
+  indent,
   insertTable,
   MARK_BOLD,
   MARK_CODE,
@@ -60,7 +63,9 @@ import {
   MARK_SUBSCRIPT,
   MARK_SUPERSCRIPT,
   MARK_UNDERLINE,
+  outdent,
   ToolbarAlign,
+  ToolbarButton,
   ToolbarElement,
   ToolbarList,
   ToolbarMark,
@@ -71,6 +76,7 @@ import { ELEMENT_CODE_BLOCK } from '@udecode/plate-code-block';
 import { ToolbarCodeBlock } from '@udecode/plate-code-block-ui';
 import { useEventEditorId } from '@udecode/plate-core';
 import { MARK_HIGHLIGHT } from '@udecode/plate-highlight';
+import { getPreventDefaultHandler } from '../../../../packages/common/src/utils/getPreventDefaultHandler';
 
 export const ToolbarButtonsBasicElements = () => {
   const editor = useStoreEditorRef(useEventEditorId('focus'));
@@ -113,6 +119,23 @@ export const ToolbarButtonsBasicElements = () => {
   );
 };
 
+export const ToolbarButtonsIndent = () => {
+  const editor = useStoreEditorRef(useEventEditorId('focus'));
+
+  return (
+    <>
+      <ToolbarButton
+        onMouseDown={editor && getPreventDefaultHandler(outdent, editor)}
+        icon={<FormatIndentDecrease />}
+      />
+      <ToolbarButton
+        onMouseDown={editor && getPreventDefaultHandler(indent, editor)}
+        icon={<FormatIndentIncrease />}
+      />
+    </>
+  );
+};
+
 export const ToolbarButtonsList = () => {
   const editor = useStoreEditorRef(useEventEditorId('focus'));
 

docs/src/live/config/initialValues.tsx

@@ -42,6 +42,20 @@ import { createElement, createList, getNodesWithRandomId } from './utils';
 
 jsx;
 
+export const initialValueIndent: any = (
+  <fragment>
+    <hh1>Changing block indentation</hh1>
+    <hp indent={1}>
+      Use the toolbar buttons to control the indentation of specific blocks. You
+      can use these tools to highlight an important piece of information,
+      communicate a hierarchy or just give your content some room.
+    </hp>
+    <hp indent={2}>
+      For instance, this paragraph looks like it belongs to the previous one.
+    </hp>
+  </fragment>
+);
+
 export const initialValueEmpty: any = (
   <fragment>
     <hp>
@@ -1204,6 +1218,7 @@ export const initialValuePlayground: any = getNodesWithRandomId([
   ...initialValueHighlight,
   ...initialValueBasicElements,
   ...initialValueHorizontalRule,
+  ...initialValueIndent,
   ...initialValueList,
   ...initialValueTables,
   ...initialValueLinks,