1 | import type { ClassName } from '@linaria/core/types/cx';
|
2 | import type { Unsubscribe } from 'nanoevents';
|
3 | import type { EditorState, EditorStateProps, EditorViewProps, PrimitiveSelection, RemirrorContentType, TextProps, Transaction, TransactionProps, TransactionTransformer } from '@remirror/core-types';
|
4 | import type { DirectEditorProps } from '@remirror/pm/view';
|
5 | import type { UpdatableViewProps } from '../builtins';
|
6 | import type { AnyExtension, AnyExtensionConstructor } from '../extension';
|
7 | import type { ManagerEvents, RemirrorManager } from '../manager';
|
8 | import type { FocusType } from '../types';
|
9 | export interface BaseFramework<Extension extends AnyExtension> {
|
10 | /**
|
11 | * The name of the framework being used.
|
12 | */
|
13 | readonly name: string;
|
14 | /**
|
15 | * The state that is initially passed into the editor.
|
16 | */
|
17 | initialEditorState: EditorState;
|
18 | /**
|
19 | * The minimum required output from the framework.
|
20 | */
|
21 | readonly frameworkOutput: FrameworkOutput<Extension>;
|
22 | /**
|
23 | * Destroy the framework and cleanup all created listeners.
|
24 | */
|
25 | destroy(): void;
|
26 | }
|
27 | export interface FrameworkOptions<Extension extends AnyExtension, Props extends FrameworkProps<Extension>> {
|
28 | /**
|
29 | * The initial editor state
|
30 | */
|
31 | initialEditorState: EditorState;
|
32 | /**
|
33 | * A method for getting the passed in props.
|
34 | */
|
35 | getProps: () => Props;
|
36 | /**
|
37 | * When provided the view will immediately be inserted into the dom within
|
38 | * this element.
|
39 | */
|
40 | element?: Element;
|
41 | }
|
42 | /**
|
43 | * The base options for an editor wrapper. This is used within the react and dom
|
44 | * implementations.
|
45 | */
|
46 | export interface FrameworkProps<Extension extends AnyExtension> {
|
47 | /**
|
48 | * Pass in the extension manager.
|
49 | *
|
50 | * The manager is responsible for handling all Prosemirror related
|
51 | * functionality.
|
52 | */
|
53 | manager: RemirrorManager<Extension>;
|
54 | /**
|
55 | * Set the starting value for the editor.
|
56 | *
|
57 | * Without setting the value prop `onChange` remirror renders as an uncontrolled
|
58 | * component. Value changes are passed back out of the editor and there is now
|
59 | * way to set the value via props. As a result this is the only opportunity to
|
60 | * directly control the rendered text.
|
61 | *
|
62 | * @defaultValue `{ type: 'doc', content: [{ type: 'paragraph' }] }`
|
63 | */
|
64 | initialContent?: RemirrorContentType | [RemirrorContentType, PrimitiveSelection];
|
65 | /**
|
66 | * Adds attributes directly to the prosemirror element.
|
67 | *
|
68 | * @defaultValue {}
|
69 | */
|
70 | attributes?: Record<string, string> | AttributePropFunction<Extension>;
|
71 | /**
|
72 | * Additional classes which can be passed into the the editor wrapper. These
|
73 | * are placed on root `Prosemirror` element and can be used to effect styling
|
74 | * within the editor.
|
75 | */
|
76 | classNames?: ClassName[];
|
77 | /**
|
78 | * Determines whether this editor is editable or not.
|
79 | *
|
80 | * @defaultValue true
|
81 | */
|
82 | editable?: boolean;
|
83 | /**
|
84 | * When set to true focus will be place on the editor as soon as it first
|
85 | * loads.
|
86 | *
|
87 | * @defaultValue false
|
88 | */
|
89 | autoFocus?: FocusType;
|
90 | /**
|
91 | * An event listener which is called whenever the editor gains focus.
|
92 | */
|
93 | onFocus?: (params: RemirrorEventListenerProps<Extension>, event: Event) => void;
|
94 | /**
|
95 | * An event listener which is called whenever the editor is blurred.
|
96 | */
|
97 | onBlur?: (params: RemirrorEventListenerProps<Extension>, event: Event) => void;
|
98 | /**
|
99 | * Called on every change to the Prosemirror state.
|
100 | */
|
101 | onChange?: RemirrorEventListener<Extension>;
|
102 | /**
|
103 | * A method called when the editor is dispatching the transaction.
|
104 | *
|
105 | * @remarks
|
106 | * Use this to update the transaction which will be used to update the editor
|
107 | * state.
|
108 | */
|
109 | onDispatchTransaction?: TransactionTransformer;
|
110 | /**
|
111 | * Sets the accessibility label for the editor instance.
|
112 | *
|
113 | * @defaultValue ''
|
114 | */
|
115 | label?: string;
|
116 | }
|
117 | export type AddFrameworkHandler<Extension extends AnyExtension> = <Key extends keyof FrameworkEvents<Extension>>(event: Key, cb: FrameworkEvents<Extension>[Key]) => Unsubscribe;
|
118 | /**
|
119 | * This is the base output that is created by a framework.
|
120 | */
|
121 | export interface FrameworkOutput<Extension extends AnyExtension> extends Remirror.ManagerStore<Extension> {
|
122 | /**
|
123 | * The manager which was used to create this editor.
|
124 | */
|
125 | manager: RemirrorManager<Extension>;
|
126 | /**
|
127 | * Add event handlers to the remirror editor at runtime.
|
128 | */
|
129 | addHandler: AddFrameworkHandler<Extension>;
|
130 | /**
|
131 | * The unique id for the editor instance.
|
132 | */
|
133 | uid: string;
|
134 | /**
|
135 | * Clears all editor content.
|
136 | *
|
137 | * @param options - includes a `triggerChange` handler which should be
|
138 | * triggered by the update.
|
139 | *
|
140 | * To use this in a controlled editor, you must set `triggerChange` to `true`.
|
141 | */
|
142 | clearContent: (options?: TriggerChangeProps) => void;
|
143 | /**
|
144 | * Replace all editor content with the new content.
|
145 | *
|
146 | * @remarks
|
147 | *
|
148 | * Allows for the editor content to be overridden by force.
|
149 | *
|
150 | * @param triggerOnChange - whether the `onChange` handler should be triggered
|
151 | * by the update. Defaults to `false`.
|
152 | *
|
153 | * To use this in a controlled editor, you must set `triggerChange` to `true`.
|
154 | */
|
155 | setContent: (content: RemirrorContentType, options?: TriggerChangeProps) => void;
|
156 | /**
|
157 | * A getter function for the current editor state. It's a wrapper around
|
158 | * `view.state`.
|
159 | */
|
160 | getState: () => EditorState;
|
161 | /**
|
162 | * A getter function for the previous prosemirror editor state. It can be used
|
163 | * to check what's changed between states.
|
164 | */
|
165 | getPreviousState: () => EditorState;
|
166 | /**
|
167 | * Get an extension by it's constructor.
|
168 | */
|
169 | getExtension: <ExtensionConstructor extends AnyExtensionConstructor>(Constructor: ExtensionConstructor) => InstanceType<ExtensionConstructor>;
|
170 | /**
|
171 | * Assert if an extension is present by it's constructor.
|
172 | */
|
173 | hasExtension: <ExtensionConstructor extends AnyExtensionConstructor>(Constructor: ExtensionConstructor) => boolean;
|
174 | /**
|
175 | * Focus the editor at the `start` | `end` a specific position or at a valid
|
176 | * range between `{ from, to }`.
|
177 | *
|
178 | * @deprecated This method may be removed in the future and it is advisable to
|
179 | * use `commands.focus()`.
|
180 | */
|
181 | focus: (position?: FocusType) => void;
|
182 | /**
|
183 | * Blur the editor.
|
184 | *
|
185 | * @deprecated This method may be removed in the future and it is advisable to
|
186 | * use `commands.blur()`.
|
187 | */
|
188 | blur: (position?: PrimitiveSelection) => void;
|
189 | }
|
190 | export type CreateStateFromContent = (content: RemirrorContentType, selection?: PrimitiveSelection) => EditorState;
|
191 | export interface RemirrorEventListenerProps<Extension extends AnyExtension> extends EditorStateProps, Remirror.ListenerProperties<Extension>, EditorViewProps {
|
192 | /**
|
193 | * The original transaction which caused this state update.
|
194 | *
|
195 | * This allows for inspecting the reason behind the state change. When
|
196 | * undefined this means that the state was updated externally.
|
197 | *
|
198 | * If available:
|
199 | * - Metadata on the transaction can be inspected. `tr.getMeta`
|
200 | * - Was the change caused by added / removed content? `tr.docChanged`
|
201 | * - Was ths change caused by an updated selection? `tr.selectionSet`
|
202 | * - `tr.steps` can be inspected for further granularity.
|
203 | */
|
204 | tr?: Transaction;
|
205 | /**
|
206 | * When the state updates are not controlled and it was a transaction that
|
207 | * caused the state to be updated this value captures all the transaction
|
208 | * updates caused by prosemirror plugins hook state methods like
|
209 | * `filterTransactions` and `appendTransactions`.
|
210 | *
|
211 | * This is for advanced users only.
|
212 | */
|
213 | transactions?: readonly Transaction[];
|
214 | /**
|
215 | * A shorthand way of checking whether the update was triggered by editor
|
216 | * usage (internal) or overwriting the state.
|
217 | *
|
218 | * - `true` The update was triggered by a change in the prosemirror doc or an
|
219 | * update to the selection. In these cases `tr` will have a value.
|
220 | * - `false` The update was caused by a call to `setContent` or `resetContent`
|
221 | */
|
222 | internalUpdate: boolean;
|
223 | /**
|
224 | * True when this is the first render of the editor. This applies when the
|
225 | * editor is first attached to the DOM.
|
226 | */
|
227 | firstRender: boolean;
|
228 | /**
|
229 | * The previous state.
|
230 | */
|
231 | previousState: EditorState;
|
232 | /**
|
233 | * Manually create a new state object with the desired content.
|
234 | */
|
235 | createStateFromContent: CreateStateFromContent;
|
236 | }
|
237 | export type RemirrorEventListener<Extension extends AnyExtension> = (params: RemirrorEventListenerProps<Extension>) => void;
|
238 | export type AttributePropFunction<Extension extends AnyExtension> = (params: RemirrorEventListenerProps<Extension>) => Record<string, string>;
|
239 | export interface PlaceholderConfig extends TextProps {
|
240 | className: string;
|
241 | }
|
242 | export interface UpdateStateProps extends Partial<TransactionProps>, EditorStateProps, TriggerChangeProps {
|
243 | /**
|
244 | * When the state updates are not controlled and it was a transaction that
|
245 | * caused the state to be updated this value captures all the transaction
|
246 | * updates caused by prosemirror plugins hook state methods like
|
247 | * `filterTransactions` and `appendTransactions`.
|
248 | *
|
249 | * This is for advanced users only.
|
250 | */
|
251 | transactions?: readonly Transaction[];
|
252 | }
|
253 | export interface TriggerChangeProps {
|
254 | /**
|
255 | * Whether or not to trigger this as a change and call any handlers.
|
256 | *
|
257 | * @defaultValue true
|
258 | */
|
259 | triggerChange?: boolean;
|
260 | }
|
261 | export interface ListenerProps extends Partial<EditorStateProps>, Partial<TransactionProps> {
|
262 | /**
|
263 | * When the state updates are not controlled and it was a transaction that
|
264 | * caused the state to be updated this value captures all the transaction
|
265 | * updates caused by prosemirror plugins hook state methods like
|
266 | * `filterTransactions` and `appendTransactions`.
|
267 | *
|
268 | * This is for advanced users only.
|
269 | */
|
270 | transactions?: readonly Transaction[];
|
271 | }
|
272 | export interface FrameworkEvents<Extension extends AnyExtension> extends Pick<ManagerEvents, 'destroy'> {
|
273 | /**
|
274 | * An event listener which is called whenever the editor gains focus.
|
275 | */
|
276 | focus: (params: RemirrorEventListenerProps<Extension>, event: Event) => void;
|
277 | /**
|
278 | * An event listener which is called whenever the editor is blurred.
|
279 | */
|
280 | blur: (params: RemirrorEventListenerProps<Extension>, event: Event) => void;
|
281 | /**
|
282 | * Called on every state update after the state has been applied to the editor.
|
283 | *
|
284 | * This should be used to track the current editor state and check if commands
|
285 | * are enabled.
|
286 | */
|
287 | updated: RemirrorEventListener<Extension>;
|
288 | }
|
289 | export type UpdatableViewPropsObject = {
|
290 | [Key in UpdatableViewProps]: DirectEditorProps[Key];
|
291 | };
|
292 | declare global {
|
293 | namespace Remirror {
|
294 | interface ListenerProperties<Extension extends AnyExtension> {
|
295 | }
|
296 | }
|
297 | }
|