1 | import type { ClassName } from '@linaria/core/types/cx';
|
2 | import type { Unsubscribe } from 'nanoevents';
|
3 | import type { EditorSchema, 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, GetSchema } 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<GetSchema<Extension>>;
|
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<GetSchema<Extension>>;
|
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 | * @default `{ type: 'doc', content: [{ type: 'paragraph' }] }`
|
63 | */
|
64 | initialContent?: RemirrorContentType | [RemirrorContentType, PrimitiveSelection];
|
65 | /**
|
66 | * Adds attributes directly to the prosemirror element.
|
67 | *
|
68 | * @default {}
|
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 | * @default 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 | * @default 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<GetSchema<Extension>>;
|
110 | /**
|
111 | * Sets the accessibility label for the editor instance.
|
112 | *
|
113 | * @default ''
|
114 | */
|
115 | label?: string;
|
116 | }
|
117 | export declare 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<GetSchema<Extension>>;
|
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<GetSchema<Extension>>;
|
166 | /**
|
167 | * Get an extension by it's constructor.
|
168 | */
|
169 | getExtension: <ExtensionConstructor extends AnyExtensionConstructor>(Constructor: ExtensionConstructor) => InstanceType<ExtensionConstructor>;
|
170 | /**
|
171 | * Focus the editor at the `start` | `end` a specific position or at a valid
|
172 | * range between `{ from, to }`.
|
173 | *
|
174 | * @deprecated This method may be removed in the future and it is advisable to
|
175 | * use `commands.focus()`.
|
176 | */
|
177 | focus: (position?: FocusType) => void;
|
178 | /**
|
179 | * Blur the editor.
|
180 | *
|
181 | * @deprecated This method may be removed in the future and it is advisable to
|
182 | * use `commands.blur()`.
|
183 | */
|
184 | blur: (position?: PrimitiveSelection) => void;
|
185 | }
|
186 | export declare type CreateStateFromContent<Extension extends AnyExtension> = (content: RemirrorContentType, selection?: PrimitiveSelection) => EditorState<GetSchema<Extension>>;
|
187 | export interface RemirrorEventListenerProps<Extension extends AnyExtension> extends EditorStateProps<GetSchema<Extension>>, Remirror.ListenerProperties<Extension>, EditorViewProps<GetSchema<Extension>> {
|
188 | /**
|
189 | * The original transaction which caused this state update.
|
190 | *
|
191 | * This allows for inspecting the reason behind the state change. When
|
192 | * undefined this means that the state was updated externally.
|
193 | *
|
194 | * If available:
|
195 | * - Metadata on the transaction can be inspected. `tr.getMeta`
|
196 | * - Was the change caused by added / removed content? `tr.docChanged`
|
197 | * - Was ths change caused by an updated selection? `tr.selectionSet`
|
198 | * - `tr.steps` can be inspected for further granularity.
|
199 | */
|
200 | tr?: Transaction<GetSchema<Extension>>;
|
201 | /**
|
202 | * When the state updates are not controlled and it was a transaction that
|
203 | * caused the state to be updated this value captures all the transaction
|
204 | * updates caused by prosemirror plugins hook state methods like
|
205 | * `filterTransactions` and `appendTransactions`.
|
206 | *
|
207 | * This is for advanced users only.
|
208 | */
|
209 | transactions?: Array<Transaction<GetSchema<Extension>>>;
|
210 | /**
|
211 | * A shorthand way of checking whether the update was triggered by editor
|
212 | * usage (internal) or overwriting the state.
|
213 | *
|
214 | * - `true` The update was triggered by a change in the prosemirror doc or an
|
215 | * update to the selection. In these cases `tr` will have a value.
|
216 | * - `false` The update was caused by a call to `setContent` or `resetContent`
|
217 | */
|
218 | internalUpdate: boolean;
|
219 | /**
|
220 | * True when this is the first render of the editor. This applies when the
|
221 | * editor is first attached to the DOM.
|
222 | */
|
223 | firstRender: boolean;
|
224 | /**
|
225 | * The previous state.
|
226 | */
|
227 | previousState: EditorState<GetSchema<Extension>>;
|
228 | /**
|
229 | * Manually create a new state object with the desired content.
|
230 | */
|
231 | createStateFromContent: CreateStateFromContent<Extension>;
|
232 | }
|
233 | export declare type RemirrorEventListener<Extension extends AnyExtension> = (params: RemirrorEventListenerProps<Extension>) => void;
|
234 | export declare type AttributePropFunction<Extension extends AnyExtension> = (params: RemirrorEventListenerProps<Extension>) => Record<string, string>;
|
235 | export interface PlaceholderConfig extends TextProps {
|
236 | className: string;
|
237 | }
|
238 | export interface UpdateStateProps<Schema extends EditorSchema = EditorSchema> extends Partial<TransactionProps<Schema>>, EditorStateProps<Schema>, TriggerChangeProps {
|
239 | /**
|
240 | * When the state updates are not controlled and it was a transaction that
|
241 | * caused the state to be updated this value captures all the transaction
|
242 | * updates caused by prosemirror plugins hook state methods like
|
243 | * `filterTransactions` and `appendTransactions`.
|
244 | *
|
245 | * This is for advanced users only.
|
246 | */
|
247 | transactions?: Array<Transaction<Schema>>;
|
248 | }
|
249 | export interface TriggerChangeProps {
|
250 | /**
|
251 | * Whether or not to trigger this as a change and call any handlers.
|
252 | *
|
253 | * @default true
|
254 | */
|
255 | triggerChange?: boolean;
|
256 | }
|
257 | export interface ListenerProps<Extension extends AnyExtension> extends Partial<EditorStateProps<GetSchema<Extension>>>, Partial<TransactionProps<GetSchema<Extension>>> {
|
258 | /**
|
259 | * When the state updates are not controlled and it was a transaction that
|
260 | * caused the state to be updated this value captures all the transaction
|
261 | * updates caused by prosemirror plugins hook state methods like
|
262 | * `filterTransactions` and `appendTransactions`.
|
263 | *
|
264 | * This is for advanced users only.
|
265 | */
|
266 | transactions?: Array<Transaction<GetSchema<Extension>>>;
|
267 | }
|
268 | export interface FrameworkEvents<Extension extends AnyExtension> extends Pick<ManagerEvents, 'destroy'> {
|
269 | /**
|
270 | * An event listener which is called whenever the editor gains focus.
|
271 | */
|
272 | focus: (params: RemirrorEventListenerProps<Extension>, event: Event) => void;
|
273 | /**
|
274 | * An event listener which is called whenever the editor is blurred.
|
275 | */
|
276 | blur: (params: RemirrorEventListenerProps<Extension>, event: Event) => void;
|
277 | /**
|
278 | * Called on every state update after the state has been applied to the editor.
|
279 | *
|
280 | * This should be used to track the current editor state and check if commands
|
281 | * are enabled.
|
282 | */
|
283 | updated: RemirrorEventListener<Extension>;
|
284 | }
|
285 | export declare type UpdatableViewPropsObject = {
|
286 | [Key in UpdatableViewProps]: DirectEditorProps[Key];
|
287 | };
|
288 | declare global {
|
289 | namespace Remirror {
|
290 | interface ListenerProperties<Extension extends AnyExtension> {
|
291 | }
|
292 | }
|
293 | }
|