@remirror/core
Version:
Where your quest to create a world class editing experience begins.
222 lines (221 loc) • 7.97 kB
TypeScript
import type { AnyFunction, CommandFunction, EditorState, EditorStateProps, EmptyShape, LiteralUnion, ProsemirrorNode, RemirrorJSON, StateJSON } from '@remirror/core-types';
import { ActiveFromExtensions, AnyExtension, AttrsFromExtensions, Helper, HelperNames, HelpersFromExtensions, PlainExtension } from '../extension';
import type { ExtensionHelperReturn } from '../types';
import { HelperDecoratorOptions } from './builtin-decorators';
import { InsertNodeOptions } from './commands-extension';
/**
* Helpers are custom methods that can provide extra functionality to the
* editor.
*
* @remarks
*
* They can be used for pulling information from the editor or performing custom
* async commands.
*
* Also provides the default helpers used within the extension.
*
* @category Builtin Extension
*/
export declare class HelpersExtension extends PlainExtension {
get name(): "helpers";
/**
* Add the `html` and `text` string handlers to the editor.
*/
onCreate(): void;
/**
* Check whether the selection is empty.
*/
isSelectionEmpty(state?: EditorState): Helper<boolean>;
isViewEditable(state?: EditorState): Helper<boolean>;
/**
* Get the full JSON output for the ProseMirror editor state object.
*/
getStateJSON(state?: EditorState): Helper<StateJSON>;
/**
* Get the JSON output for the main ProseMirror `doc` node.
*
* This can be used to persist data between sessions and can be passed as
* content to the `initialContent` prop.
*/
getJSON(state?: EditorState): Helper<RemirrorJSON>;
/**
* @deprecated use `getJSON` instead.
*/
getRemirrorJSON(state?: EditorState): Helper<RemirrorJSON>;
/**
* Insert a html string as a ProseMirror Node.
*
* @category Builtin Command
*/
insertHtml(html: string, options?: InsertNodeOptions): CommandFunction;
/**
* A method to get all the content in the editor as text. Depending on the
* content in your editor, it is not guaranteed to preserve it 100%, so it's
* best to test that it meets your needs before consuming.
*/
getText({ lineBreakDivider, state, }?: GetTextHelperOptions): Helper<string>;
getTextBetween(from: number, to: number, doc?: ProsemirrorNode): Helper<string>;
/**
* Get the html from the current state, or provide a custom state.
*/
getHTML(state?: EditorState): Helper<string>;
/**
* Wrap the content in a pre tag to preserve whitespace and see what the
* editor does with it.
*/
private textToProsemirrorNode;
}
interface GetTextHelperOptions extends Partial<EditorStateProps> {
/**
* The divider used to separate text blocks.
*
* @defaultValue '\n\n'
*/
lineBreakDivider?: string;
}
declare global {
namespace Remirror {
interface ManagerStore<Extension extends AnyExtension> {
/**
* The helpers provided by the extensions used.
*/
helpers: HelpersFromExtensions<Extension>;
/**
* Check which nodes and marks are active under the current user
* selection.
*
* ```ts
* const { active } = manager.store;
*
* return active.bold() ? 'bold' : 'regular';
* ```
*/
active: ActiveFromExtensions<Extension>;
/**
* Get the attributes for the named node or mark from the current user
* selection.
*
* ```ts
* const { attrs } = manager.store;
*
* attrs.heading(); // => { id: 'i1238ha', level: 1 }
* ```
*/
attrs: AttrsFromExtensions<Extension>;
}
interface BaseExtension {
/**
* `ExtensionHelpers`
*
* This pseudo property makes it easier to infer Generic types of this
* class.
*
* @internal
*/
['~H']: this['createHelpers'] extends AnyFunction ? ReturnType<this['createHelpers']> : EmptyShape;
/**
* @experimental
*
* Stores all the helpers that have been added via decorators to the
* extension instance. This is used by the `HelpersExtension` to pick the
* helpers.
*
* @internal
*/
decoratedHelpers?: Record<string, HelperDecoratorOptions>;
/**
* A helper method is a function that takes in arguments and returns a
* value depicting the state of the editor specific to this extension.
*
* @remarks
*
* Unlike commands they can return anything and may not effect the
* behavior of the editor.
*
* Below is an example which should provide some idea on how to add
* helpers to the app.
*
* ```tsx
* // extension.ts
* import { ExtensionFactory } from '@remirror/core';
*
* const MyBeautifulExtension = ExtensionFactory.plain({
* name: 'beautiful',
* createHelpers: () => ({
* checkBeautyLevel: () => 100
* }),
* })
* ```
*
* ```
* // app.tsx
* import { useRemirrorContext } from '@remirror/react';
*
* const MyEditor = () => {
* const { helpers } = useRemirrorContext({ autoUpdate: true });
*
* return helpers.beautiful.checkBeautyLevel() > 50
* ? (<span>😍</span>)
* : (<span>😢</span>);
* };
* ```
*/
createHelpers?(): ExtensionHelperReturn;
}
interface StringHandlers {
/**
* Register the plain `text` string handler which renders a text string
* inside a `<pre />`.
*/
text: HelpersExtension;
/**
* Register the html string handler, which converts a html string to a
* prosemirror node.
*/
html: HelpersExtension;
}
interface ExtensionStore {
/**
* Helper method to provide information about the content of the editor.
* Each extension can register its own helpers.
*
* This should only be accessed after the `onView` lifecycle method
* otherwise it will throw an error.
*/
helpers: HelpersFromExtensions<Extensions>;
/**
* Check which nodes and marks are active under the current user
* selection.
*
* ```ts
* const { active } = manager.store;
*
* return active.bold() ? 'bold' : 'regular';
* ```
*/
active: ActiveFromExtensions<Extensions>;
/**
* Get the attributes for the named node or mark from the current user
* selection.
*
* ```ts
* const { attrs } = manager.store;
*
* attrs.heading(); // => { id: 'i1238ha', level: 1 }
* ```
*/
attrs: AttrsFromExtensions<Extensions>;
}
interface ListenerProperties<Extension extends AnyExtension> {
helpers: HelpersFromExtensions<Extension>;
}
interface AllExtensions {
helpers: HelpersExtension;
}
}
/**
* The helpers name for all extension defined in the current project.
*/
type AllHelperNames = LiteralUnion<HelperNames<Remirror.Extensions>, string>;
}
export {};