-
Notifications
You must be signed in to change notification settings - Fork 29.9k
/
index.d.ts
505 lines (471 loc) · 15.4 KB
/
index.d.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
// Type definitions for @wordpress/blocks 9.1
// Project: https://github.com/WordPress/gutenberg/tree/master/packages/blocks/README.md
// Definitions by: Derek Sifford <https://github.com/dsifford>
// Jon Surrell <https://github.com/sirreal>
// Dennis Snell <https://github.com/dmsnell>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// TypeScript Version: 3.6
import { Dashicon } from '@wordpress/components';
import { dispatch, select } from '@wordpress/data';
import { ComponentType, ReactElement } from 'react';
export * from './api';
export { withBlockContentContext } from './block-content-provider';
declare module '@wordpress/data' {
function dispatch(key: 'core/blocks'): typeof import('./store/actions');
function select(key: 'core/blocks'): typeof import('./store/selectors');
}
export type BlockAlignment = 'left' | 'center' | 'right' | 'wide' | 'full';
export interface BlockEditProps<T extends Record<string, any>> extends BlockSaveProps<T> {
readonly className: string;
readonly clientId: string;
readonly isSelected: boolean;
readonly setAttributes: (attrs: Partial<T>) => void;
}
export interface BlockIconNormalized {
background?: string | undefined;
foreground?: string | undefined;
shadowColor?: string | undefined;
src: Dashicon.Icon | ReactElement | ComponentType;
}
export type BlockIcon = BlockIconNormalized['src'] | BlockIconNormalized;
export interface BlockSaveProps<T extends Record<string, any>> {
readonly attributes: Readonly<T>;
}
export interface BlockStyle {
readonly name: string;
readonly label: string;
readonly isDefault?: boolean | undefined;
}
/**
* Internal type for the innerBlocks property inside of the example
*
* @internal
* @see Block.example
* @see {@link https://github.com/DefinitelyTyped/DefinitelyTyped/pull/55245#discussion_r692208988}
*/
type BlockExampleInnerBlock = Partial<Block> &
Pick<Block, 'name' | 'attributes'> & {
innerBlocks?: ReadonlyArray<BlockExampleInnerBlock>;
};
export interface Block<T extends Record<string, any> = {}> {
/**
* The version of the Block API used by the block.
*
* @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#api-version}
*/
readonly apiVersion?: number;
/**
* Attributes for the block.
*/
readonly attributes: {
readonly [k in keyof T]: BlockAttribute<T[k] extends Array<infer U> ? U : T[k]>;
};
/**
* The block category (determines placement in the inserter).
*/
readonly category: string;
/**
* Array of deprecation handlers for the block.
*/
readonly deprecated?: ReadonlyArray<BlockDeprecation<T>> | undefined;
/**
* This is a short description for your block, which can be translated
* with our translation functions.
*/
readonly description?: string | undefined;
/**
* Component to render in the editor.
*/
readonly edit?: ComponentType<BlockEditProps<T>> | undefined;
/**
* Block type editor script definition.
* It will only be enqueued in the context of the editor.
*
* @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#editor-script}
*/
readonly editorScript?: string;
/**
* Block type editor style definition.
* It will only be enqueued in the context of the editor.
*
* @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#editor-style}
*/
readonly editorStyle?: string;
/**
* It provides structured example data for the block.
*
* @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#example}
*/
readonly example?: Readonly<Partial<Block> & { innerBlocks?: ReadonlyArray<BlockExampleInnerBlock> }>;
/**
* Icon for the block.
*/
readonly icon: BlockIconNormalized;
/**
* Searchable keywords for discovery.
*/
readonly keywords?: readonly string[] | undefined;
/**
* Setting `parent` lets a block require that it is only available when
* nested within the specified blocks.
*/
readonly parent?: readonly string[] | undefined;
/**
* Context provided for available access by descendants of blocks of this
* type, in the form of an object which maps a context name to one of the
* block’s own attribute.
*
* @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#provides-context}
*/
readonly providesContext?: Record<string, keyof T>;
/**
* This is set internally when registering the type.
*/
readonly name: string;
/**
* Component to render on the frontend.
*/
readonly save: ComponentType<BlockSaveProps<T>>;
/**
* Block type frontend script definition.
* It will be enqueued both in the editor and when viewing the content on
* the front of the site.
*
* @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#script}
*/
readonly script?: string;
/**
* Block type editor style definition.
* It will only be enqueued in the context of the editor.
*
* @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#style}
*/
readonly style?: string;
/**
* Block styles.
*
* @see `https://wordpress.org/gutenberg/handbook/extensibility/extending-blocks/#block-style-variations`
*/
readonly styles?: readonly BlockStyle[] | undefined;
/**
* Optional block extended support features.
*/
readonly supports?: BlockSupports | undefined;
/**
* The gettext text domain of the plugin/block.
*
* @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#text-domain}
*/
readonly textdomain?: string;
/**
* This is the display title for your block, which can be translated
* with our translation functions.
*/
readonly title: string;
/**
* Block transformations.
*/
readonly transforms?: {
/**
* Transforms from another block type to this block type.
*/
readonly from?: ReadonlyArray<Transform<T>> | undefined;
/**
* Transforms from this block type to another block type.
*/
readonly to?: readonly Transform[] | undefined;
} | undefined;
/**
* Array of the names of context values to inherit from an ancestor
* provider.
*
* @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#context}
*/
readonly usesContext?: string[];
/**
* The current version number of the block, such as 1.0 or 1.0.3.
*
* @see {@link https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#version}
*/
readonly version?: string;
/**
* Sets attributes on the topmost parent element of the current block.
*/
getEditWrapperProps?(attrs: T): Record<string, string | number | boolean>;
/**
* Undocumented, but used in core.
*
* @see `@wordpress/block-library/src/paragraph`
*/
merge?(attributes: T, attributesToMerge: T): Partial<T>;
}
export type BlockConfiguration<T extends Record<string, any> = {}> = Partial<Omit<Block<T>, 'icon'>> &
Pick<Block<T>, 'attributes' | 'category' | 'title'> & {
icon?: BlockIcon | undefined;
};
export interface BlockInstance<T extends Record<string, any> = { [k: string]: any }> {
/**
* Attributes for the block.
*/
readonly attributes: T;
/**
* Unique ID registered to the block.
*/
readonly clientId: string;
/**
* Array of inner blocks, if the block has any.
*/
readonly innerBlocks: BlockInstance[];
/**
* Indicates whether or not the block is valid.
*/
readonly isValid: boolean;
/**
* The block's registered name.
*/
readonly name: string;
/**
* The parsed HTML content of the block.
*/
readonly originalContent?: string | undefined;
}
export interface BlockDeprecation<T extends Record<string, any>>
extends Pick<Block<T>, 'attributes' | 'save' | 'supports'> {
/**
* A function which, given the attributes and inner blocks of the
* parsed block, returns true if the deprecation can handle the block
* migration. This is particularly useful in cases where a block is
* technically valid even once deprecated, and requires updates to its
* attributes or inner blocks.
*/
isEligible?(attributes: Record<string, any>, innerBlocks: BlockInstance[]): boolean;
/**
* A function which, given the old attributes and inner blocks is
* expected to return either the new attributes or a tuple array of
* [attributes, innerBlocks] compatible with the block.
*/
migrate?(attributes: Record<string, any>): T;
migrate?(attributes: Record<string, any>, innerBlocks: BlockInstance[]): [T, BlockInstance[]];
}
//
// Supports
// ----------------------------------------------------------------------------
export interface BlockSupports {
/**
* This property adds block controls which allow to change block's
* alignment.
*
* @defaultValue false
*/
readonly align?: boolean | readonly BlockAlignment[] | undefined;
/**
* Enable wide alignment (depends on `align`).
*
* @defaultValue true
*/
readonly alignWide?: boolean | undefined;
/**
* Anchors let you link directly to a specific block on a page. This
* property adds a field to define an id for the block and a button to
* copy the direct link.
*
* @defaultValue false
*/
readonly anchor?: boolean | undefined;
/**
* This property adds a field to define a custom className for the
* block's wrapper.
*
* @defaultValue true
*/
readonly customClassName?: boolean | undefined;
/**
* By default, Gutenberg adds a class with the form
* `.wp-block-your-block-name` to the root element of your saved
* markup.
*
* @defaultValue true
*/
readonly className?: boolean | undefined;
/**
* By default, Gutenberg will allow a block's markup to be edited
* individually. To disable this behavior, set `html` to `false`
*
* @defaultValue true
*/
readonly html?: boolean | undefined;
/**
* By default, all blocks will appear in the Gutenberg inserter. To
* hide a block so that it can only be inserted programmatically, set
* to false
*
* @defaultValue true
*/
readonly inserter?: boolean | undefined;
/**
* A non-multiple block can be inserted into each post, one time only.
*
* @defaultValue true
*/
readonly multiple?: boolean | undefined;
/**
* By default all blocks can be converted to a reusable block.
*
* @defaultValue true
*/
readonly reusable?: boolean | undefined;
}
//
// Attributes
// ----------------------------------------------------------------------------
export namespace AttributeSource {
type Attribute = {
source: 'attribute';
attribute: string;
selector?: string | undefined;
} & (
| {
type: 'boolean';
default?: boolean | undefined;
}
| {
type: 'number';
default?: number | undefined;
}
| {
type: 'string';
default?: string | undefined;
});
interface Children {
source: 'children';
type: 'array';
selector?: string | undefined;
}
interface HTML {
source: 'html';
type: 'string';
multiline?: 'li' | 'p' | undefined;
selector?: string | undefined;
default?: string | undefined;
}
interface Meta {
source: 'meta';
type: 'string';
meta: string;
default?: string | undefined;
}
interface Query<T> {
source: 'query';
type: 'array';
selector: string;
query: {
[k in keyof T]: BlockAttribute<T[k] extends Array<infer U> ? U : T[k]>;
};
default?: any[] | undefined;
}
interface Text {
source: 'text';
type: 'string';
selector?: string | undefined;
default?: string | undefined;
}
type None = {
source?: never | undefined;
} & (
| {
type: 'array';
default?: any[] | undefined;
}
| {
type: 'object';
default?: object | undefined;
}
| {
type: 'boolean';
default?: boolean | undefined;
}
| {
type: 'number';
default?: number | undefined;
}
| {
type: 'string';
default?: string | undefined;
})
| 'array'
| 'object'
| 'boolean'
| 'number'
| 'string';
}
export type BlockAttribute<T> =
| AttributeSource.Attribute
| AttributeSource.Children
| AttributeSource.HTML
| AttributeSource.Meta
| AttributeSource.Query<T>
| AttributeSource.Text
| AttributeSource.None;
//
// Transforms
// ----------------------------------------------------------------------------
export type TransformRawSchema = {
[k in keyof HTMLElementTagNameMap | '#text']?: {
attributes?: string[] | undefined;
require?: Array<keyof HTMLElementTagNameMap> | undefined;
classes?: Array<string | RegExp> | undefined;
children?: TransformRawSchema | undefined;
};
};
export interface TransformBlock<T extends Record<string, any>> {
type: 'block';
priority?: number | undefined;
blocks: string[];
isMatch?(attributes: T): boolean;
isMultiBlock?: boolean | undefined;
transform(attributes: T): BlockInstance<Partial<T>>;
}
export interface TransformEnter<T extends Record<string, any>> {
type: 'enter';
priority?: number | undefined;
regExp: RegExp;
transform(): BlockInstance<Partial<T>>;
}
export interface TransformFiles<T extends Record<string, any>> {
type: 'files';
priority?: number | undefined;
isMatch?(files: FileList): boolean;
transform(files: FileList, onChange?: (id: string, attrs: T) => void): BlockInstance<Partial<T>>;
}
export interface TransformPrefix<T extends Record<string, any>> {
type: 'prefix';
priority?: number | undefined;
prefix: string;
transform(content: string): BlockInstance<Partial<T>>;
}
export interface TransformRaw<T extends Record<string, any>> {
type: 'raw';
priority?: number | undefined;
/**
* Comma-separated list of selectors, no spaces.
*
* @example 'p,div,h1,.css-class,#id'
*/
selector?: string | undefined;
schema?: TransformRawSchema | undefined;
isMatch?(node: Node): boolean;
transform?(node: Node): BlockInstance<Partial<T>> | void;
}
export interface TransformShortcode<T extends Record<string, any>> {
type: 'shortcode';
priority?: number | undefined;
tag: string;
attributes?: any; // TODO: add stronger types here.
}
export type Transform<T extends Record<string, any> = Record<string, any>> =
| TransformBlock<T>
| TransformEnter<T>
| TransformFiles<T>
| TransformPrefix<T>
| TransformRaw<T>
| TransformShortcode<T>;