1 | import type { ExtensionPriority } from '@remirror/core-constants';
|
2 | import type { AnyFunction, CommandFunction, KeyBindingCommandFunction, Listable, LiteralUnion, NonChainableCommandFunction, ProsemirrorAttributes, Shape } from '@remirror/core-types';
|
3 | import type { I18n } from '@remirror/i18n';
|
4 | import type { CoreIcon } from '@remirror/icons';
|
5 | import type { AnyExtension, HelperAnnotation } from '../extension';
|
6 | import type { GetOptions, TypedPropertyDescriptor } from '../types';
|
7 | /**
|
8 | * A decorator which can be applied to top level methods on an extension to
|
9 | * identify them as helpers. This can be used as a replacement for the
|
10 | * `createHelpers` method.
|
11 | *
|
12 | * To allow the TypeScript compiler to automatically infer types, please create
|
13 | * your methods with the following type signature.
|
14 | *
|
15 | * ```ts
|
16 | * import { CommandFunction } from '@remirror/core';
|
17 | *
|
18 | * type Signature = (...args: any[]) => CommandFunction;
|
19 | * ```
|
20 | *
|
21 | * The following is an example of how this can be used within your extension.
|
22 | *
|
23 | * ```ts
|
24 | * import { helper, Helper } from '@remirror/core';
|
25 | *
|
26 | * class MyExtension {
|
27 | * get name() {
|
28 | * return 'my';
|
29 | * }
|
30 | *
|
31 | * @helper()
|
32 | * alwaysTrue(): Helper<boolean> {
|
33 | * return true;
|
34 | * }
|
35 | * }
|
36 | * ```
|
37 | *
|
38 | * The above helper can now be used within your editor instance.
|
39 | *
|
40 | * ```tsx
|
41 | * import { useRemirrorContext } from '@remirror/react';
|
42 | *
|
43 | * const MyEditorButton = () => {
|
44 | * const { helpers } = useRemirrorContext();
|
45 | *
|
46 | * return helpers.alwaysTrue() ? <button>My Button</button> : null
|
47 | * }
|
48 | * ```
|
49 | *
|
50 | * @category Method Decorator
|
51 | */
|
52 | export declare function helper(options?: HelperDecoratorOptions): <Extension extends AnyExtension, Type>(target: Extension, propertyKey: string, _descriptor: TypedPropertyDescriptor<AnyFunction<NonNullable<Type> extends HelperAnnotation ? Type : never>>) => void;
|
53 | /**
|
54 | * A decorator which can be applied to top level methods on an extension to
|
55 | * identify them as commands. This can be used as a replacement for the
|
56 | * `createCommands` method.
|
57 | *
|
58 | * If you prefer not to use decorators, then you can continue using
|
59 | * `createCommands`. Internally the decorators are being used as they are better
|
60 | * for documentation purposes.
|
61 | *
|
62 | * For automated type inference methods that use this decorator must implement
|
63 | * the following type signature.
|
64 | *
|
65 | * ```ts
|
66 | * import { CommandFunction } from '@remirror/core';
|
67 | *
|
68 | * type Signature = (...args: any[]) => CommandFunction;
|
69 | * ```
|
70 | *
|
71 | * The following is an example of how this can be used within your extension.
|
72 | *
|
73 | * ```ts
|
74 | * import { command, CommandFunction } from '@remirror/core';
|
75 | *
|
76 | * class MyExtension {
|
77 | * get name() {
|
78 | * return 'my';
|
79 | * }
|
80 | *
|
81 | * @command()
|
82 | * myCommand(text: string): CommandFunction {
|
83 | * return ({ tr, dispatch }) => {
|
84 | * dispatch?.(tr.insertText('my command ' + text));
|
85 | * return true;
|
86 | * }
|
87 | * }
|
88 | * }
|
89 | * ```
|
90 | *
|
91 | * The above command can now be used within your editor instance.
|
92 | *
|
93 | * ```tsx
|
94 | * import { useRemirrorContext } from '@remirror/react';
|
95 | *
|
96 | * const MyEditorButton = () => {
|
97 | * const { commands } = useRemirrorContext();
|
98 | *
|
99 | * return <button onClick={() => commands.myCommand('hello')}>My Button</button>
|
100 | * }
|
101 | * ```
|
102 | *
|
103 | * @category Method Decorator
|
104 | */
|
105 | export declare function command<Extension extends AnyExtension>(options?: ChainableCommandDecoratorOptions<Required<GetOptions<Extension>>>): ExtensionDecorator<Extension, CommandFunction, void>;
|
106 | export declare function command<Extension extends AnyExtension>(options: NonChainableCommandDecoratorOptions<Required<GetOptions<Extension>>>): ExtensionDecorator<Extension, NonChainableCommandFunction, void>;
|
107 | /**
|
108 | * A decorator which can be applied to an extension method to
|
109 | * identify as a key binding method. This can be used as a replacement for
|
110 | * the `createKeymap` method depending on your preference.
|
111 | *
|
112 | * If you prefer not to use decorators, then you can continue using
|
113 | * `createKeymap`.
|
114 | *
|
115 | * @category Method Decorator
|
116 | */
|
117 | export declare function keyBinding<Extension extends AnyExtension>(options: KeybindingDecoratorOptions<Required<GetOptions<Extension>>>): (target: Extension, propertyKey: string, _descriptor: TypedPropertyDescriptor<KeyBindingCommandFunction>) => void;
|
118 | export interface HelperDecoratorOptions {
|
119 | }
|
120 | export type KeyboardShortcutFunction<Options extends Shape = Shape> = (options: Options, store: Remirror.ExtensionStore) => KeyboardShortcut;
|
121 | export type KeyboardShortcutValue = Listable<LiteralUnion<'Enter' | 'ArrowDown' | 'ArrowUp' | 'ArrowLeft' | 'ArrowRight' | 'Escape' | 'Delete' | 'Backspace', string>>;
|
122 | export type KeyboardShortcut = KeyboardShortcutValue | KeyboardShortcutFunction;
|
123 | export interface KeybindingDecoratorOptions<Options extends Shape = Shape> {
|
124 | /**
|
125 | * The keypress sequence to intercept.
|
126 | *
|
127 | * - `Enter`
|
128 | * - `Shift-Enter`
|
129 | */
|
130 | shortcut: KeyboardShortcut;
|
131 | /**
|
132 | * This can be used to set a keybinding as inactive based on the provided
|
133 | * options.
|
134 | */
|
135 | isActive?: (options: Options, store: Remirror.ExtensionStore) => boolean;
|
136 | /**
|
137 | * The priority for this keybinding.
|
138 | */
|
139 | priority?: ExtensionPriority | ((options: Options, store: Remirror.ExtensionStore) => ExtensionPriority);
|
140 | /**
|
141 | * The name of the command that the keybinding should be attached to.
|
142 | */
|
143 | command?: Remirror.AllUiCommandNames;
|
144 | }
|
145 | type ExtensionDecorator<Extension extends AnyExtension, Fn, Return> = (target: Extension, propertyKey: string, _descriptor: TypedPropertyDescriptor<AnyFunction<Fn>>) => Return;
|
146 | export interface CommandUiIcon {
|
147 | /**
|
148 | * The icon name.
|
149 | */
|
150 | name: CoreIcon;
|
151 | /**
|
152 | * Text placed in a superscript position. For `ltr` this is in the top right
|
153 | * hand corner of the icon.
|
154 | */
|
155 | sup?: string;
|
156 | /**
|
157 | * Text placed in a subscript position. For `ltr` this is in the bottom right
|
158 | * hand corner.
|
159 | */
|
160 | sub?: string;
|
161 | }
|
162 | export type CommandDecoratorShortcut = string | {
|
163 | shortcut: string;
|
164 | attrs: ProsemirrorAttributes;
|
165 | } | string[] | Array<{
|
166 | shortcut: string;
|
167 | attrs: ProsemirrorAttributes;
|
168 | }>;
|
169 | export interface CommandUiDecoratorOptions {
|
170 | /**
|
171 | * The default command icon to use if this has a UI representation.
|
172 | */
|
173 | icon?: CommandDecoratorValue<CoreIcon | CommandUiIcon>;
|
174 | /**
|
175 | * A label for the command with support for i18n. This makes use of
|
176 | * `babel-plugin-macros` to generate the message.
|
177 | */
|
178 | label?: CommandDecoratorMessage;
|
179 | /**
|
180 | * An i18n compatible description which can be used to provide extra context
|
181 | * for the command.
|
182 | */
|
183 | description?: CommandDecoratorMessage;
|
184 | /**
|
185 | * A keyboard shortcut which can be used to run the specified command.
|
186 | *
|
187 | * Rather than defining this here, you should create a decorated `keyBinding`
|
188 | * and set the `command` name option. This way the shortcut will dynamically
|
189 | * be added at runtime.
|
190 | */
|
191 | shortcut?: CommandDecoratorShortcut;
|
192 | }
|
193 | export interface CommandDecoratorMessageProps {
|
194 | /**
|
195 | * True when the command is enabled.
|
196 | */
|
197 | enabled: boolean;
|
198 | /**
|
199 | * True when the extension is active.
|
200 | */
|
201 | active: boolean;
|
202 | /**
|
203 | * Predefined attributes which can influence the returned value.
|
204 | */
|
205 | attrs: ProsemirrorAttributes | undefined;
|
206 | /**
|
207 | * A translation utility for translating a predefined string / or message
|
208 | * descriptor.
|
209 | */
|
210 | t: I18n['_'];
|
211 | }
|
212 | /**
|
213 | * @typeParam Value - the value which should be returned from the function or
|
214 | * used directly.
|
215 | */
|
216 | export type CommandDecoratorValue<Value> = ((props: CommandDecoratorMessageProps) => Value) | Value;
|
217 | export type CommandDecoratorMessage = CommandDecoratorValue<string>;
|
218 | interface ChainableCommandDecoratorOptions<Options extends Shape> extends Remirror.CommandDecoratorOptions<Options> {
|
219 | /**
|
220 | * Set this to `true` to disable chaining of this command. This means it will
|
221 | * no longer be available when running `
|
222 | *
|
223 | * @defaultValue false
|
224 | */
|
225 | disableChaining?: false;
|
226 | }
|
227 | interface NonChainableCommandDecoratorOptions<Options extends Shape> extends Remirror.CommandDecoratorOptions<Options> {
|
228 | /**
|
229 | * Set this to `true` to disable chaining of this command. This means it will
|
230 | * no longer be available when running `
|
231 | *
|
232 | * @defaultValue false
|
233 | */
|
234 | disableChaining: true;
|
235 | }
|
236 | export type CommandDecoratorOptions<Options extends Shape = Shape> = ChainableCommandDecoratorOptions<Options> | NonChainableCommandDecoratorOptions<Options>;
|
237 | declare global {
|
238 | namespace Remirror {
|
239 | /**
|
240 | * UX options for the command which can be extended.
|
241 | */
|
242 | interface CommandDecoratorOptions<Options extends Shape = Shape> extends CommandUiDecoratorOptions {
|
243 | /**
|
244 | * A function which can be used to override whether a command is already
|
245 | * active for the current selection.
|
246 | */
|
247 | active?: (options: Options, store: ExtensionStore) => boolean;
|
248 | }
|
249 | }
|
250 | }
|
251 | export {};
|