1 | import type { AnyFunction, CommandFunction, EditorState, EditorStateProps, EmptyShape, LiteralUnion, ProsemirrorNode, RemirrorJSON, StateJSON } from '@remirror/core-types';
|
2 | import { ActiveFromExtensions, AnyExtension, AttrsFromExtensions, Helper, HelperNames, HelpersFromExtensions, PlainExtension } from '../extension';
|
3 | import type { ExtensionHelperReturn } from '../types';
|
4 | import { HelperDecoratorOptions } from './builtin-decorators';
|
5 | import { InsertNodeOptions } from './commands-extension';
|
6 | /**
|
7 | * Helpers are custom methods that can provide extra functionality to the
|
8 | * editor.
|
9 | *
|
10 | * @remarks
|
11 | *
|
12 | * They can be used for pulling information from the editor or performing custom
|
13 | * async commands.
|
14 | *
|
15 | * Also provides the default helpers used within the extension.
|
16 | *
|
17 | * @category Builtin Extension
|
18 | */
|
19 | export declare class HelpersExtension extends PlainExtension {
|
20 | get name(): "helpers";
|
21 | /**
|
22 | * Add the `html` and `text` string handlers to the editor.
|
23 | */
|
24 | onCreate(): void;
|
25 | /**
|
26 | * Check whether the selection is empty.
|
27 | */
|
28 | isSelectionEmpty(state?: EditorState): Helper<boolean>;
|
29 | isViewEditable(state?: EditorState): Helper<boolean>;
|
30 | /**
|
31 | * Get the full JSON output for the ProseMirror editor state object.
|
32 | */
|
33 | getStateJSON(state?: EditorState): Helper<StateJSON>;
|
34 | /**
|
35 | * Get the JSON output for the main ProseMirror `doc` node.
|
36 | *
|
37 | * This can be used to persist data between sessions and can be passed as
|
38 | * content to the `initialContent` prop.
|
39 | */
|
40 | getJSON(state?: EditorState): Helper<RemirrorJSON>;
|
41 | /**
|
42 | * @deprecated use `getJSON` instead.
|
43 | */
|
44 | getRemirrorJSON(state?: EditorState): Helper<RemirrorJSON>;
|
45 | /**
|
46 | * Insert a html string as a ProseMirror Node.
|
47 | *
|
48 | * @category Builtin Command
|
49 | */
|
50 | insertHtml(html: string, options?: InsertNodeOptions): CommandFunction;
|
51 | /**
|
52 | * A method to get all the content in the editor as text. Depending on the
|
53 | * content in your editor, it is not guaranteed to preserve it 100%, so it's
|
54 | * best to test that it meets your needs before consuming.
|
55 | */
|
56 | getText({ lineBreakDivider, state, }?: GetTextHelperOptions): Helper<string>;
|
57 | getTextBetween(from: number, to: number, doc?: ProsemirrorNode): Helper<string>;
|
58 | /**
|
59 | * Get the html from the current state, or provide a custom state.
|
60 | */
|
61 | getHTML(state?: EditorState): Helper<string>;
|
62 | /**
|
63 | * Wrap the content in a pre tag to preserve whitespace and see what the
|
64 | * editor does with it.
|
65 | */
|
66 | private textToProsemirrorNode;
|
67 | }
|
68 | interface GetTextHelperOptions extends Partial<EditorStateProps> {
|
69 | /**
|
70 | * The divider used to separate text blocks.
|
71 | *
|
72 | * @defaultValue '\n\n'
|
73 | */
|
74 | lineBreakDivider?: string;
|
75 | }
|
76 | declare global {
|
77 | namespace Remirror {
|
78 | interface ManagerStore<Extension extends AnyExtension> {
|
79 | /**
|
80 | * The helpers provided by the extensions used.
|
81 | */
|
82 | helpers: HelpersFromExtensions<Extension>;
|
83 | /**
|
84 | * Check which nodes and marks are active under the current user
|
85 | * selection.
|
86 | *
|
87 | * ```ts
|
88 | * const { active } = manager.store;
|
89 | *
|
90 | * return active.bold() ? 'bold' : 'regular';
|
91 | * ```
|
92 | */
|
93 | active: ActiveFromExtensions<Extension>;
|
94 | /**
|
95 | * Get the attributes for the named node or mark from the current user
|
96 | * selection.
|
97 | *
|
98 | * ```ts
|
99 | * const { attrs } = manager.store;
|
100 | *
|
101 | * attrs.heading(); // => { id: 'i1238ha', level: 1 }
|
102 | * ```
|
103 | */
|
104 | attrs: AttrsFromExtensions<Extension>;
|
105 | }
|
106 | interface BaseExtension {
|
107 | /**
|
108 | * `ExtensionHelpers`
|
109 | *
|
110 | * This pseudo property makes it easier to infer Generic types of this
|
111 | * class.
|
112 | *
|
113 | * @internal
|
114 | */
|
115 | ['~H']: this['createHelpers'] extends AnyFunction ? ReturnType<this['createHelpers']> : EmptyShape;
|
116 | /**
|
117 | * @experimental
|
118 | *
|
119 | * Stores all the helpers that have been added via decorators to the
|
120 | * extension instance. This is used by the `HelpersExtension` to pick the
|
121 | * helpers.
|
122 | *
|
123 | * @internal
|
124 | */
|
125 | decoratedHelpers?: Record<string, HelperDecoratorOptions>;
|
126 | /**
|
127 | * A helper method is a function that takes in arguments and returns a
|
128 | * value depicting the state of the editor specific to this extension.
|
129 | *
|
130 | * @remarks
|
131 | *
|
132 | * Unlike commands they can return anything and may not effect the
|
133 | * behavior of the editor.
|
134 | *
|
135 | * Below is an example which should provide some idea on how to add
|
136 | * helpers to the app.
|
137 | *
|
138 | * ```tsx
|
139 | * // extension.ts
|
140 | * import { ExtensionFactory } from '@remirror/core';
|
141 | *
|
142 | * const MyBeautifulExtension = ExtensionFactory.plain({
|
143 | * name: 'beautiful',
|
144 | * createHelpers: () => ({
|
145 | * checkBeautyLevel: () => 100
|
146 | * }),
|
147 | * })
|
148 | * ```
|
149 | *
|
150 | * ```
|
151 | * // app.tsx
|
152 | * import { useRemirrorContext } from '@remirror/react';
|
153 | *
|
154 | * const MyEditor = () => {
|
155 | * const { helpers } = useRemirrorContext({ autoUpdate: true });
|
156 | *
|
157 | * return helpers.beautiful.checkBeautyLevel() > 50
|
158 | * ? (<span>😍</span>)
|
159 | * : (<span>😢</span>);
|
160 | * };
|
161 | * ```
|
162 | */
|
163 | createHelpers?(): ExtensionHelperReturn;
|
164 | }
|
165 | interface StringHandlers {
|
166 | /**
|
167 | * Register the plain `text` string handler which renders a text string
|
168 | * inside a `<pre />`.
|
169 | */
|
170 | text: HelpersExtension;
|
171 | /**
|
172 | * Register the html string handler, which converts a html string to a
|
173 | * prosemirror node.
|
174 | */
|
175 | html: HelpersExtension;
|
176 | }
|
177 | interface ExtensionStore {
|
178 | /**
|
179 | * Helper method to provide information about the content of the editor.
|
180 | * Each extension can register its own helpers.
|
181 | *
|
182 | * This should only be accessed after the `onView` lifecycle method
|
183 | * otherwise it will throw an error.
|
184 | */
|
185 | helpers: HelpersFromExtensions<Extensions>;
|
186 | /**
|
187 | * Check which nodes and marks are active under the current user
|
188 | * selection.
|
189 | *
|
190 | * ```ts
|
191 | * const { active } = manager.store;
|
192 | *
|
193 | * return active.bold() ? 'bold' : 'regular';
|
194 | * ```
|
195 | */
|
196 | active: ActiveFromExtensions<Extensions>;
|
197 | /**
|
198 | * Get the attributes for the named node or mark from the current user
|
199 | * selection.
|
200 | *
|
201 | * ```ts
|
202 | * const { attrs } = manager.store;
|
203 | *
|
204 | * attrs.heading(); // => { id: 'i1238ha', level: 1 }
|
205 | * ```
|
206 | */
|
207 | attrs: AttrsFromExtensions<Extensions>;
|
208 | }
|
209 | interface ListenerProperties<Extension extends AnyExtension> {
|
210 | helpers: HelpersFromExtensions<Extension>;
|
211 | }
|
212 | interface AllExtensions {
|
213 | helpers: HelpersExtension;
|
214 | }
|
215 | }
|
216 | /**
|
217 | * The helpers name for all extension defined in the current project.
|
218 | */
|
219 | type AllHelperNames = LiteralUnion<HelperNames<Remirror.Extensions>, string>;
|
220 | }
|
221 | export {};
|