@remirror/ui

The new version of remirror comes with a number of enhancements and quite a few breaking changes if you were using the remirror@1.0.0-next.* pre-releases.

The following sections outline the breaking changes and how they can be migrated if your last version was @next. For those upgrading from 0.11.0 the library has changed drastically and you'd be better off browsing the documentation.

When you install the top level remirror package you are given access to every extension developed by remirror via the remirror/extension entry point.

- import { BoldExtension } from 'remirror/extension/bold';
- import { ItalicExtension } from 'remirror/extension/italic';
+ import { BoldExtension, ItalicExtension } from 'remirror/extensions';

You can also still install the extensions directly from their scoped packages.

import { BoldExtension } from '@remirror/extension-bold';

If your code is importing from remirror/react you should now change the import to @remirror/react.

- import { useManager } from 'remirror/react';
+ import { useRemirror } from '@remirror/react';

• Rename the original useRemirror to now be called useRemirrorContext.
• Add new @remirror/react-components package.
• @remirror/react exports all the hooks, components, core modules and react specific extensions from @remirror/react-core, @remirror/react-components, @remirror/react-hooks and @remirror/extension-react.

useManager was too focused on the implementation details. We've updated the API to be used in a different way and useRemirror is now the way to initialize an editor.

import React from 'react';
import { BoldExtension, ItalicExtension, UnderlineExtension } from 'remirror/extensions';
import { Remirror, useRemirror } from '@remirror/react';

const extensions = () => [new BoldExtension(), new ItalicExtension(), new UnderlineExtension()];

const Editor = () => {
  const { manager } = useRemirror({ extensions });

  return <Remirror manager={manager} />;
};

The previous useRemirror is now called useRemirrorContext since it plucks the context from the outer Remirror Component. The <RemirrorProvider /> has been renamed to <Remirror /> and automatically renders an editor.

When no children are provided to the <Remirror /> component it will automatically render a container div where the prosemirror editor will be placed. If you do add children it is up to you to import the <EditorComponent /> and add it to the children or set the autoRender prop to 'start' | 'end' | true.

useManager has been marked as @internal (although it is still exported) and going forward you should be using useRemirror as shown in the above example.

@remirror/preset-table is now @remirror/extension-tables. The TableExtension uses the new createExtension method to inject the TableRowExtension which in turn injects the TableCellExtension and TableHeaderCellExtension. To use tables in your editor the following is sufficient.

import { TableExtension } from 'remirror/extensions';
import { Remirror, useRemirror } from '@remirror/react';

const Editor = () => {
  const { manager } = useRemirror({ extensions: () => [TableExtension()] });

  return <Remirror manager={manager} />;
};

• New Rect interface returned by the positioner x: number; y: number; width: number; height: number;

• Added visible property which shows if the position currently visible within the editor viewport.

• Improved scrolling when using the positioner.

• Fixed a lot of bugs in the positioner API.

• This DOMRect represents an absolute position within the document. It is up to your consuming component to consume the rect.

• Renamed the positioners in line with the new functionality.

import React from 'react';
import { BoldExtension, CorePreset, ItalicExtension, MarkdownExtension } from 'remirror/extension';
import { Remirror, useRemirror } from '@remirror/react';

const Editor = () => {
  const { manager, onChange, state } = useRemirror({
    extensions: () => [new BoldExtension(), new ItalicExtension()],
    content: '<p><strong>I am strong.</strong> and <em>I am emphasized</em></p>',
    stringHandler: 'html',
  });

  return <Remirror manager={manager} onChange={onChange} state={state} />;
};

• Rename useKeymap to useKeymaps. The original useKeymap now has a different signature.

import { useCallback } from 'react';
import { BoldExtension } from 'remirror/extensions';
import { Remirror, useHelpers, useKeymap, useRemirror, useRemirrorContext } from '@remirror/react';

const hooks = [
  () => {
    const active = useActive();
    const { insertText } = useCommands();
    const boldActive = active.bold();
    const handler = useCallback(() => {
      if (!boldActive) {
        return false;
      }

      return insertText.original('\n\nWoah there!')(props);
    }, [boldActive, insertText]);

    useKeymap('Shift-Enter', handler); // Add the handler to the keypress pattern.
  },
];

const Editor = () => {
  const { manager } = useRemirror({ extensions: () => [new BoldExtension()] });

  return <Remirror manager={manager} hooks={hooks} />;
};

• Editor selection now defaults to the end of the document. You can change the starting point as shown below.

  import { Remirror, useRemirror } from '@remirror/react';
  
  const Editor = () => {
    const { manager, state } = useRemirror({ selection: 'start' });
  
    return <Remirror manger={manager} initialState={state} />;
  };
  

• All interfaces which were named with the pattern *Parameter have been renamed to to *Props. The only exceptions are *FrameworkParameter which are now *FrameworkOptions.

• Remove Presets completely. In their place a function that returns a list of Extensions should be used. They were clunky, difficult to use and provided little to no value.

• Remove @remirror/core entry-point and add all core exports to the main remirror entry-point.

• Add all Extensions and Preset package exports to the remirror/extensions subdirectory. It doesn't include framework specific exports which are made available from @remirror/react.

• Rename @remirror/preset-table to @remirror/extension-tables.

• Rename preset-list to extension-lists. ListPreset is now BulletListExtension and OrderListExtension.

• Create new decorator pattern for adding @commands, @helper functions and @keyBindings.

• Deprecate tags property on extension and encourage the use of createTags which is a method instead.

• Rename interface CreatePluginReturn to CreateExtensionPlugin.

• Add support for directly updating the doc attributes.

• Deprecate top level context methods focus and blur. They should now be consumed as commands.

The following packages have been removed.

• Remove @remirror/showcase
• Remove @remirror/react-social
• Remove @remirror/react-wysiwyg
• Remove package @remirror/extension-auto-link. The functionality is now self-contained within @remirror/extension-link.

• New createDecorations extension method for adding decorations to the ProseMirror EditorView.
• New lifecycle methods: onInitState, onApplyState, and onApplyTransaction lifecycle methods. These correspond exactly the the plugin methods which ProseMirror exposes and can be used to create plugin functionality without creating a new plugin.
• @command, @keyBinding, @helper decorators for increased type safety when configuring extensions.
• NamedShortcut keybindings which can be set on the keymap extension. Currently remirror defaults to using the same shortcuts as Google Docs.
• Add the nodeOverrides property to the extensions which for advanced users allows overriding of the default NodeSpec and MarkSpec.
• Rename addOrReplacePlugins to updatePlugins in ExtensionStore.
• Remove reconfigureStatePlugins and auto apply it for all plugin updating methods.

• Make sure all your commands in an extension are annotated with a return type of CommandFunction. Failure to do so will break all type inference wherever the extension is used.

  import { CommandFunction } from 'remirror';
  

• When setting the name of the extension make sure to use as const otherwise it will be a string and ruin autocompletion for extension names, nodes and marks.

  class MyExtension extends PlainExtension {
    get name() {
      return 'makeItConst' as const;
    }
  }
  

• The Remirror component now has a convenient hooks props. The hooks prop takes an array of zero parameter hook functions which are rendered into the RemirrorContext. It's a shorthand to writing out your own components. You can see the pattern in use above.

There are new hooks for working with commands.

• Each command has an original method attached for using the original command that was used to create the command. The original command has the same type signature as the (...args: any[]) => CommandFunction. So you would call it with the command arguments and then also provide the CommandProps. This is useful when composing commands together or using commands within keyBindings which need to return a boolean.

  • You can see the insertText.original being used in the useKeymap example above.

• useCommands() provides all the commands as hook. useChainedCommands provides all the chainable commands.

  import { useCallback } from 'react';
  import { useChainedCommands, useKeymap } from '@remirror/react';
  
  function useLetItGo() {
    const chain = useChainedCommands();
    const handler = useCallback(() => {
      chain.selectText('all').insertText('Let it goo 🤫').run();
    }, [chain]);
  
    // Whenever the user types `a` they let it all go
    useKeymap('a', handler);
  }
  

• Upgrade React to require minimum versions of ^16.14.0 || ^17. This is because of the codebase now using the new jsx transform.
• Upgrade TypeScript to a minimum of 4.3. Several of the new features make use of the new types and it is a requirement to upgrade.
• General upgrades across all dependencies to using the latest versions.
  • All prosemirror-* packages.

• 🚀 @remirror/react, @remirror/editor-wysiwyg, @remirror/editor-social: New extensions props on the RemirrorManager for injecting additional extensions into prebuilt editors https://github.com/ifiokjr/remirror/pull/176.

• jest-prosemirror: New snapshot serializer exported as prosemirrorSerializer.
• jest-prosemirror: New debug method which logs the editor's prettified html to the console.
• prosemirror-suggest: Now supports ignoring activation characters to prevent matches from appearing in ignored sections.

• @remirror/extension-mention: Fix a long standing bug where the editor crashes after deleting a single character mention.

• 🚀 @remirror/react-hooks: New package for shared react hooks.

• 🚀 @remirror/react-portals: New package for the remirror / react portals.

• 🚀 @remirror/react-node-view: New package for prosemirror node views built with react components.

• 🚀 @remirror/dev: New package developing extensions and components.

• 🚀 prosemirror-suggest: New package for managing prosemirror suggestions.

• 🚀 test-keyboard: New package for dispatching keyboard events.

• 🚀 @remirror/ui, @remirror/ui-buttons, @remirror/ui-dropdown, @remirror/ui-icons, @remirror/ui-menus, @remirror/ui-modal, @remirror/ui-text: New packages and several utilities for managing the ui of a remirror editor.

• 🚀 @remirror/core: Introduce the concept of meta tags for extensions. These allow an extension to tag itself and these tags are made available through the tag object which is passed to all extension methods.

• 🚀 @remirror/core: Add a helpers method to extensions. These are similar to commands except they don't have access to the view and shouldn't directly affect the editor. They can also return data and receive custom parameters. They can be accessed with manager.data.helpers.myHelper().

• 🚀 @remirror/core-extensions: Add TrailingNodeExtension to always append a specified node to the end of the dom.

• @remirror/core: Add getExtraAttrs method to the extension which can be used in the (Mark/Node)Extension.

• 🚀 @remirror/core: Add DropCursorExtension for a cursor to show up at the exact location an item will be dropped.

• 🚀 @remirror/core: Add GapCursorExtension for support of tricky to select locations.

• Introduce new @builtin annotation to show when an extension is included by default.

• Introduce new @schema annotation for extension options to indicated that an option should not be updated after creating or it will change the schema.

• New command yarn generate:json which auto generates json files for support/rollup/rollup.config.js, support/storybook/.babelrc.js, support/tsconfig.paths.json and .size-limit.json. Previously these were maintained manually.

• 💥 BREAKING @remirror/react-renderer: Updated the name of @remirror/renderer-react for consistency.

• 💥 BREAKING @remirror/core: @emotion/core is now a peerDependency. When adding this library to your project you will need to yarn add @emotion/core as well. This is required to prevent bugs with version conflicts within the EmotionThemeProvider.

• 💥 BREAKING @remirror/core: deepMerge now takes multiple parameters instead of one array of objects to merge.

• 💥 BREAKING @remirror/core @remirror/core-extensions and all extensions: Refactor ExtensionTypes with a whole set of helpers for better type checking and self documenting types. Now the remirror component can receive the List of Extensions and from this infer the nodes, marks and actions available on any editor. Currently this inference has only been added to the Wysiwyg editor but will be added to the Twitter editor and all future editors.

• 💥 BREAKING @remirror/core @remirror/core-extensions: Move ParagraphExtension from core to core-extensions. The reason is to not pollute the core library with formatting methods which are primarily just for extensions.

• 💥 BREAKING @remirror/core: Rename ExtensionType.EXTENSION = 'extension' to ExtensionType.Plain = 'plain'.

• 💥 BREAKING @remirror/ui: Rename @remirror/react-components to @remirror/ui. It is now the base component that will be used for all ui related functionality.

• 💥 BREAKING @remirror/react-utils: Refactor the type signature of node views and improve their design. Now node view takes attrs and options.

• 💥 BREAKING @remirror/react: Rename NodeViewPortalComponent to RemirrorPortals since it now supports decorations.

• 💥 BREAKING @remirror/react: Change the name of useRemirror to useRemirrorContext.

• 💥 BREAKING @remirror/editor-social: Rename @remirror/editor-twitter to @remirror/editor-social for branding reasons.

• 💥 BREAKING @remirror/core: Rename NodeViewPortalContainer to PortalContainer.

• 💥 BREAKING @remirror/core: Refactor the type signature of SSRComponents to only take a node and options extraAttrs configuration to enable parsing the dom.

• 💥 BREAKING jest-prosemirror: Names of matchers have been changed. transformsPMNode is now toTransformNode and toEqualPMNode is now toEqualProsemirrorNode.

• @remirror/core: Update extraAttrs configuration to enable parsing the dom.

• @remirror/core: Make default priority level for extensions 3 instead of 2. A lower number means the extension is deemed more important and ordered earlier in lists.

• @remirror/core-extensions: Add extraAttrs to the following extensions: LinkExtension, ParagraphExtension, HeadingExtension.

• 💥 BREAKING @remirror/renderer-react: Removed package.
• 💥 BREAKING @remirror/react-utils: Remove placeholder prop from the RemirrorManager.
• 💥 BREAKING @remirror/react: Remove higher order components.
• 💥 BREAKING @remirror/react: Remove withoutEmotion prop. This should now be configured via the RemirrorThemeProvider component.