1 | import type { ExtensionPriority } from '@remirror/core-constants';
|
2 | import type { AnyConstructor, AnyFunction, CommandFunction, EditorState, EditorStateProps, GetDynamic, GetFixedDynamic, GetPartialDynamic, PrimitiveSelection, RemoveAnnotations, Transaction, ValidOptions } from '@remirror/core-types';
|
3 | import type { PluginSpec } from '@remirror/pm/state';
|
4 | type Changes<Type> = {
|
5 | /**
|
6 | * Whether or not the value has changed.
|
7 | *
|
8 | * - `false` when no change occurred.
|
9 | */
|
10 | changed: false;
|
11 | } | {
|
12 | /**
|
13 | * - `true` when a change occurred.
|
14 | */
|
15 | changed: true;
|
16 | /**
|
17 | * The previous value before the changed. This is only accessible when
|
18 | * `changed` is `true`.
|
19 | */
|
20 | previousValue: Type;
|
21 | /**
|
22 | * The latest value after the change. This is only accessible when
|
23 | * `changed` is `true`.
|
24 | */
|
25 | value: Type;
|
26 | };
|
27 | /**
|
28 | * Highlights all the properties that have changed.
|
29 | */
|
30 | export type ChangedOptions<Options extends ValidOptions> = {
|
31 | [Key in keyof GetDynamic<Options>]: Changes<GetDynamic<Options>[Key]>;
|
32 | };
|
33 | /**
|
34 | * Get the static extension settings.
|
35 | */
|
36 | export type GetOptions<Type extends {
|
37 | ['~O']: unknown;
|
38 | }> = Type['~O'];
|
39 | /**
|
40 | * Get the commands from a `RemirrorManager`, `Extension` or `Preset`.
|
41 | */
|
42 | export type GetCommands<Type extends {
|
43 | ['~C']: unknown;
|
44 | }> = Type['~C'];
|
45 | /**
|
46 | * Get the helpers provided by an from a `RemirrorManager`, `Extension` or
|
47 | * `Preset`.
|
48 | */
|
49 | export type GetHelpers<Type extends {
|
50 | ['~H']: unknown;
|
51 | }> = Type['~H'];
|
52 | /**
|
53 | * Get the constructor of an instance.
|
54 | */
|
55 | export type GetConstructor<Type extends {
|
56 | constructor: unknown;
|
57 | }> = Type['constructor'];
|
58 | /**
|
59 | * Get the options from any constructor. Can be used for both presets and
|
60 | * extensions.
|
61 | */
|
62 | export type OptionsOfConstructor<Constructor extends AnyConstructor> = GetOptions<InstanceType<Constructor>>;
|
63 | /**
|
64 | * Get the options from any constructor. Can be used for both presets and
|
65 | * extensions.
|
66 | */
|
67 | export type DynamicOptionsOfConstructor<Constructor extends AnyConstructor> = GetPartialDynamic<GetOptions<InstanceType<Constructor>>>;
|
68 | /**
|
69 | * The extension store which is shared across all extensions. It provides access
|
70 | * to methods and data that can be used throughout the extension lifecycle.
|
71 | */
|
72 | export interface ExtensionStore extends Remirror.ExtensionStore {
|
73 | }
|
74 | export type ExtensionCommandFunction = (...args: any[]) => CommandFunction;
|
75 | /**
|
76 | * The return signature for an extensions command method.
|
77 | */
|
78 | export interface ExtensionCommandReturn {
|
79 | [command: string]: ExtensionCommandFunction;
|
80 | }
|
81 | /**
|
82 | * The return signature for an extensions helper method.
|
83 | */
|
84 | export interface ExtensionHelperReturn {
|
85 | [helper: string]: AnyFunction;
|
86 | }
|
87 | /**
|
88 | * The type of a non chainable command. It is a function with an `isEnabled`
|
89 | * method to check whether the command can be run.
|
90 | */
|
91 | export interface CommandShape<Parameter extends any[] = []> {
|
92 | /**
|
93 | * Returns true when the command can be run and false when it can't be run. It
|
94 | * basically runs the command without dispatching it to see whether it returns
|
95 | * true or false.
|
96 | *
|
97 | * @remarks
|
98 | *
|
99 | * Some commands can have rules and restrictions. For example, formatting like
|
100 | *`bold` is disabled within a `codeBlock`. In this case
|
101 | *`commands.toggleBold.isEnabled()` returns `false` when within a `codeBlock`
|
102 | *and `true` when outside.
|
103 | *
|
104 | * @param args - The same arguments that are applied to the command function.
|
105 | */
|
106 | enabled: (...args: Parameter) => boolean;
|
107 | /**
|
108 | * @deprecated use `enabled` instead.
|
109 | */
|
110 | isEnabled: (...args: Parameter) => boolean;
|
111 | /**
|
112 | * This function gives you access to the original command defined by the
|
113 | * extension in your editor exactly as it was defined.
|
114 | *
|
115 | * The function returns a function that takes the CommandFunctionProps of
|
116 | * `{ state, dispatch?, tr, view? }` object.
|
117 | *
|
118 | * ```ts
|
119 | * function command(...args: any[]) => CommandFunction;
|
120 | * ```
|
121 | */
|
122 | original: (...args: Parameter) => CommandFunction;
|
123 | /**
|
124 | * Commands which are not attached to a node extension or a mark extension can
|
125 | * optionally define custom `isActive` checker.
|
126 | *
|
127 | * This is used for checking if `centerAlign` is active from the
|
128 | * `@remirror/extension-node-formatting`.
|
129 | */
|
130 | active?: () => boolean;
|
131 | (...args: Parameter): void;
|
132 | }
|
133 | export interface ApplyStateLifecycleProps extends EditorStateProps {
|
134 | /**
|
135 | * The original transaction which caused this state update.
|
136 | */
|
137 | tr: Transaction;
|
138 | /**
|
139 | * The previous state.
|
140 | */
|
141 | previousState: EditorState;
|
142 | }
|
143 | export interface AppendLifecycleProps extends EditorStateProps {
|
144 | /**
|
145 | * Update this transaction in order to append.
|
146 | */
|
147 | tr: Transaction;
|
148 | /**
|
149 | * The previous state.
|
150 | */
|
151 | previousState: EditorState;
|
152 | /**
|
153 | * The transactions that have already been applied.
|
154 | */
|
155 | transactions: readonly Transaction[];
|
156 | }
|
157 | export interface StateUpdateLifecycleProps extends EditorStateProps {
|
158 | /**
|
159 | * The previous state.
|
160 | */
|
161 | previousState: EditorState;
|
162 | /**
|
163 | * When true, this lets you know that it is the first state update to happen.
|
164 | * This can be used to run an action that should only be run when the state is
|
165 | * first available.
|
166 | */
|
167 | firstUpdate: boolean;
|
168 | /**
|
169 | * The original transaction which caused this state update.
|
170 | *
|
171 | * This allows for inspecting the reason behind the state change.
|
172 | * When undefined this means that the state was updated externally.
|
173 | *
|
174 | * If available:
|
175 | * - Metadata on the transaction can be inspected. `tr.getMeta`
|
176 | * - Was the change caused by added / removed content? `tr.docChanged`
|
177 | * - Was ths change caused by an updated selection? `tr.selectionSet`
|
178 | * - `tr.steps` can be inspected for further granularity.
|
179 | */
|
180 | tr?: Transaction;
|
181 | /**
|
182 | * When the state updates are not controlled and it was a transaction that
|
183 | * caused the state to be updated this value captures all the transaction
|
184 | * updates caused by prosemirror plugins hook state methods like
|
185 | * `filterTransactions` and `appendTransactions`.
|
186 | *
|
187 | * This is for advanced users only, and I personally have never needed it.
|
188 | */
|
189 | transactions?: readonly Transaction[];
|
190 | }
|
191 | export interface BaseExtensionOptions extends Remirror.BaseExtensionOptions {
|
192 | /**
|
193 | * An object which excludes certain functionality from an extension.
|
194 | */
|
195 | exclude?: ExcludeOptions;
|
196 | /**
|
197 | * The priority with which this extension should be loaded by the manager.
|
198 | *
|
199 | * @remarks
|
200 | *
|
201 | * Each priority level corresponds to a higher level of importance for the
|
202 | * extension within the editor.
|
203 | *
|
204 | * When this is set to `null` the `defaultPriority` level for the extension
|
205 | * will be used instead.
|
206 | */
|
207 | priority?: ExtensionPriority;
|
208 | }
|
209 | export interface ExcludeOptions extends Partial<Remirror.ExcludeOptions> {
|
210 | }
|
211 | /**
|
212 | * @internal
|
213 | */
|
214 | export type UpdateReason = 'set' | 'reset';
|
215 | export interface UpdateReasonProps {
|
216 | /**
|
217 | * Describes what triggered an update.
|
218 | *
|
219 | * - `set` - the change was triggered by an update in some properties
|
220 | * - `reset` - the user has specifically requested to reset all properties to
|
221 | * their initial defaults
|
222 | * - `init` - the update is happening when the preset is being It will receive
|
223 | * all the items as changes.
|
224 | */
|
225 | reason: UpdateReason;
|
226 | }
|
227 | export interface GetChangeOptionsReturn<Options extends ValidOptions> {
|
228 | /**
|
229 | * The next value of the properties after the update.This also includes values
|
230 | * which have not been changed.
|
231 | */
|
232 | options: GetFixedDynamic<Options>;
|
233 | /**
|
234 | * An object with all the keys showing what's been changed. This should be
|
235 | * used to determine the children extensions which should be updated.
|
236 | *
|
237 | * @remarks
|
238 | *
|
239 | * Using this can prevent unnecessary updates. It's possible for new
|
240 | * properties to be passed that are identical to the previous, by checking if
|
241 | * the object was changed this can be avoided.
|
242 | *
|
243 | * This uses a discriminated union. When the `changed` property is true then
|
244 | * the object has a value as well.
|
245 | *
|
246 | * ```ts
|
247 | * if (changes.myProperty.changed) {
|
248 | * doSomething(changes.myProperty.value);
|
249 | * }
|
250 | * ```
|
251 | */
|
252 | changes: Readonly<Required<ChangedOptions<Options>>>;
|
253 | /**
|
254 | * Pick the changed values by their key. An object populated with only the
|
255 | * changed items will be returned to you.
|
256 | */
|
257 | pickChanged: PickChanged<Options>;
|
258 | }
|
259 | export type PickChanged<Options extends ValidOptions> = <Key extends keyof GetFixedDynamic<Options>>(keys: Key[]) => Partial<Pick<GetFixedDynamic<Options>, Key>>;
|
260 | export interface OnSetOptionsProps<Options extends ValidOptions> extends Pick<GetChangeOptionsReturn<Options>, 'changes' | 'pickChanged'>, UpdateReasonProps {
|
261 | /**
|
262 | * The initial options for the extension. Falls back to default options.
|
263 | */
|
264 | initialOptions: RemoveAnnotations<GetFixedDynamic<Options>>;
|
265 | /**
|
266 | * The next value of the properties after the update.This also includes values
|
267 | * which have not been changed.
|
268 | */
|
269 | options: RemoveAnnotations<GetFixedDynamic<Options>>;
|
270 | }
|
271 | declare global {
|
272 | namespace Remirror {
|
273 | /**
|
274 | * A global type which allows setting additional options on the exclude.
|
275 | */
|
276 | interface ExcludeOptions {
|
277 | }
|
278 | /**
|
279 | * A global type which allows additional default settings to be added to the
|
280 | * editor.
|
281 | */
|
282 | interface BaseExtensionOptions {
|
283 | }
|
284 | }
|
285 | }
|
286 | /**
|
287 | * An interface for creating custom plugins in your `remirror` editor.
|
288 | */
|
289 | export interface CreateExtensionPlugin<PluginState = any> extends Pick<PluginSpec<PluginState>, 'props' | 'state' | 'key' | 'view' | 'filterTransaction' | 'appendTransaction'> {
|
290 | /**
|
291 | Additional properties are allowed on plugin specs, which can be
|
292 | read via [`Plugin.spec`](https://prosemirror.net/docs/ref/#state.Plugin.spec).
|
293 | */
|
294 | [key: string]: any;
|
295 | }
|
296 | /**
|
297 | * A helper interface for creating strongly typed decorators.
|
298 | */
|
299 | export interface TypedPropertyDescriptor<Type> {
|
300 | configurable?: boolean;
|
301 | enumerable?: boolean;
|
302 | value?: Type;
|
303 | writable?: boolean;
|
304 | get?: () => Type;
|
305 | set?: (v: Type) => void;
|
306 | }
|
307 | /**
|
308 | * The type of arguments acceptable for the focus parameter.
|
309 | *
|
310 | * - Can be a prosemirror selection
|
311 | * - A range of `{ from: number; to: number }`
|
312 | * - A single position with a `number`
|
313 | * - A string of `'start' | 'end'`
|
314 | * - `true` which sets the focus to the current position or start.
|
315 | */
|
316 | export type FocusType = PrimitiveSelection | boolean;
|
317 | export {};
|