-
Notifications
You must be signed in to change notification settings - Fork 4.1k
/
index.js
654 lines (596 loc) · 19.3 KB
/
index.js
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
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
/**
* External dependencies
*/
import { Tokenizer } from 'simple-html-tokenizer';
import {
identity,
xor,
fromPairs,
isEqual,
includes,
stubTrue,
} from 'lodash';
/**
* WordPress dependencies
*/
import { decodeEntities } from '@wordpress/html-entities';
/**
* Internal dependencies
*/
import { createLogger, createQueuedLogger } from './logger';
import { getSaveContent } from '../serializer';
import { normalizeBlockType } from '../utils';
/**
* Globally matches any consecutive whitespace
*
* @type {RegExp}
*/
const REGEXP_WHITESPACE = /[\t\n\r\v\f ]+/g;
/**
* Matches a string containing only whitespace
*
* @type {RegExp}
*/
const REGEXP_ONLY_WHITESPACE = /^[\t\n\r\v\f ]*$/;
/**
* Matches a CSS URL type value
*
* @type {RegExp}
*/
const REGEXP_STYLE_URL_TYPE = /^url\s*\(['"\s]*(.*?)['"\s]*\)$/;
/**
* Boolean attributes are attributes whose presence as being assigned is
* meaningful, even if only empty.
*
* See: https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#boolean-attributes
* Extracted from: https://html.spec.whatwg.org/multipage/indices.html#attributes-3
*
* Object.keys( Array.from( document.querySelectorAll( '#attributes-1 > tbody > tr' ) )
* .filter( ( tr ) => tr.lastChild.textContent.indexOf( 'Boolean attribute' ) !== -1 )
* .reduce( ( result, tr ) => Object.assign( result, {
* [ tr.firstChild.textContent.trim() ]: true
* } ), {} ) ).sort();
*
* @type {Array}
*/
const BOOLEAN_ATTRIBUTES = [
'allowfullscreen',
'allowpaymentrequest',
'allowusermedia',
'async',
'autofocus',
'autoplay',
'checked',
'controls',
'default',
'defer',
'disabled',
'download',
'formnovalidate',
'hidden',
'ismap',
'itemscope',
'loop',
'multiple',
'muted',
'nomodule',
'novalidate',
'open',
'playsinline',
'readonly',
'required',
'reversed',
'selected',
'typemustmatch',
];
/**
* Enumerated attributes are attributes which must be of a specific value form.
* Like boolean attributes, these are meaningful if specified, even if not of a
* valid enumerated value.
*
* See: https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#enumerated-attribute
* Extracted from: https://html.spec.whatwg.org/multipage/indices.html#attributes-3
*
* Object.keys( Array.from( document.querySelectorAll( '#attributes-1 > tbody > tr' ) )
* .filter( ( tr ) => /^("(.+?)";?\s*)+/.test( tr.lastChild.textContent.trim() ) )
* .reduce( ( result, tr ) => Object.assign( result, {
* [ tr.firstChild.textContent.trim() ]: true
* } ), {} ) ).sort();
*
* @type {Array}
*/
const ENUMERATED_ATTRIBUTES = [
'autocapitalize',
'autocomplete',
'charset',
'contenteditable',
'crossorigin',
'decoding',
'dir',
'draggable',
'enctype',
'formenctype',
'formmethod',
'http-equiv',
'inputmode',
'kind',
'method',
'preload',
'scope',
'shape',
'spellcheck',
'translate',
'type',
'wrap',
];
/**
* Meaningful attributes are those who cannot be safely ignored when omitted in
* one HTML markup string and not another.
*
* @type {Array}
*/
const MEANINGFUL_ATTRIBUTES = [
...BOOLEAN_ATTRIBUTES,
...ENUMERATED_ATTRIBUTES,
];
/**
* Array of functions which receive a text string on which to apply normalizing
* behavior for consideration in text token equivalence, carefully ordered from
* least-to-most expensive operations.
*
* @type {Array}
*/
const TEXT_NORMALIZATIONS = [
identity,
getTextWithCollapsedWhitespace,
];
/**
* Regular expression matching a named character reference. In lieu of bundling
* a full set of references, the pattern covers the minimal necessary to test
* positively against the full set.
*
* "The ampersand must be followed by one of the names given in the named
* character references section, using the same case."
*
* Tested aginst "12.5 Named character references":
*
* ```
* const references = Array.from( document.querySelectorAll(
* '#named-character-references-table tr[id^=entity-] td:first-child'
* ) ).map( ( code ) => code.textContent )
* references.every( ( reference ) => /^[\da-z]+$/i.test( reference ) )
* ```
*
* @see https://html.spec.whatwg.org/multipage/syntax.html#character-references
* @see https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references
*
* @type {RegExp}
*/
const REGEXP_NAMED_CHARACTER_REFERENCE = /^[\da-z]+$/i;
/**
* Regular expression matching a decimal character reference.
*
* "The ampersand must be followed by a U+0023 NUMBER SIGN character (#),
* followed by one or more ASCII digits, representing a base-ten integer"
*
* @see https://html.spec.whatwg.org/multipage/syntax.html#character-references
*
* @type {RegExp}
*/
const REGEXP_DECIMAL_CHARACTER_REFERENCE = /^#\d+$/;
/**
* Regular expression matching a hexadecimal character reference.
*
* "The ampersand must be followed by a U+0023 NUMBER SIGN character (#), which
* must be followed by either a U+0078 LATIN SMALL LETTER X character (x) or a
* U+0058 LATIN CAPITAL LETTER X character (X), which must then be followed by
* one or more ASCII hex digits, representing a hexadecimal integer"
*
* @see https://html.spec.whatwg.org/multipage/syntax.html#character-references
*
* @type {RegExp}
*/
const REGEXP_HEXADECIMAL_CHARACTER_REFERENCE = /^#x[\da-f]+$/i;
/**
* Returns true if the given string is a valid character reference segment, or
* false otherwise. The text should be stripped of `&` and `;` demarcations.
*
* @param {string} text Text to test.
*
* @return {boolean} Whether text is valid character reference.
*/
export function isValidCharacterReference( text ) {
return (
REGEXP_NAMED_CHARACTER_REFERENCE.test( text ) ||
REGEXP_DECIMAL_CHARACTER_REFERENCE.test( text ) ||
REGEXP_HEXADECIMAL_CHARACTER_REFERENCE.test( text )
);
}
/**
* Subsitute EntityParser class for `simple-html-tokenizer` which uses the
* implementation of `decodeEntities` from `html-entities`, in order to avoid
* bundling a massive named character reference.
*
* @see https://github.com/tildeio/simple-html-tokenizer/tree/master/src/entity-parser.ts
*/
export class DecodeEntityParser {
/**
* Returns a substitute string for an entity string sequence between `&`
* and `;`, or undefined if no substitution should occur.
*
* @param {string} entity Entity fragment discovered in HTML.
*
* @return {?string} Entity substitute value.
*/
parse( entity ) {
if ( isValidCharacterReference( entity ) ) {
return decodeEntities( '&' + entity + ';' );
}
}
}
/**
* Given a specified string, returns an array of strings split by consecutive
* whitespace, ignoring leading or trailing whitespace.
*
* @param {string} text Original text.
*
* @return {string[]} Text pieces split on whitespace.
*/
export function getTextPiecesSplitOnWhitespace( text ) {
return text.trim().split( REGEXP_WHITESPACE );
}
/**
* Given a specified string, returns a new trimmed string where all consecutive
* whitespace is collapsed to a single space.
*
* @param {string} text Original text.
*
* @return {string} Trimmed text with consecutive whitespace collapsed.
*/
export function getTextWithCollapsedWhitespace( text ) {
// This is an overly simplified whitespace comparison. The specification is
// more prescriptive of whitespace behavior in inline and block contexts.
//
// See: https://medium.com/@patrickbrosset/when-does-white-space-matter-in-html-b90e8a7cdd33
return getTextPiecesSplitOnWhitespace( text ).join( ' ' );
}
/**
* Returns attribute pairs of the given StartTag token, including only pairs
* where the value is non-empty or the attribute is a boolean attribute, an
* enumerated attribute, or a custom data- attribute.
*
* @see MEANINGFUL_ATTRIBUTES
*
* @param {Object} token StartTag token.
*
* @return {Array[]} Attribute pairs.
*/
export function getMeaningfulAttributePairs( token ) {
return token.attributes.filter( ( pair ) => {
const [ key, value ] = pair;
return (
value ||
key.indexOf( 'data-' ) === 0 ||
includes( MEANINGFUL_ATTRIBUTES, key )
);
} );
}
/**
* Returns true if two text tokens (with `chars` property) are equivalent, or
* false otherwise.
*
* @param {Object} actual Actual token.
* @param {Object} expected Expected token.
* @param {Object} logger Validation logger object.
*
* @return {boolean} Whether two text tokens are equivalent.
*/
export function isEquivalentTextTokens( actual, expected, logger = createLogger() ) {
// This function is intentionally written as syntactically "ugly" as a hot
// path optimization. Text is progressively normalized in order from least-
// to-most operationally expensive, until the earliest point at which text
// can be confidently inferred as being equal.
let actualChars = actual.chars;
let expectedChars = expected.chars;
for ( let i = 0; i < TEXT_NORMALIZATIONS.length; i++ ) {
const normalize = TEXT_NORMALIZATIONS[ i ];
actualChars = normalize( actualChars );
expectedChars = normalize( expectedChars );
if ( actualChars === expectedChars ) {
return true;
}
}
logger.warning( 'Expected text `%s`, saw `%s`.', expected.chars, actual.chars );
return false;
}
/**
* Given a style value, returns a normalized style value for strict equality
* comparison.
*
* @param {string} value Style value.
*
* @return {string} Normalized style value.
*/
export function getNormalizedStyleValue( value ) {
return value
// Normalize URL type to omit whitespace or quotes
.replace( REGEXP_STYLE_URL_TYPE, 'url($1)' );
}
/**
* Given a style attribute string, returns an object of style properties.
*
* @param {string} text Style attribute.
*
* @return {Object} Style properties.
*/
export function getStyleProperties( text ) {
const pairs = text
// Trim ending semicolon (avoid including in split)
.replace( /;?\s*$/, '' )
// Split on property assignment
.split( ';' )
// For each property assignment...
.map( ( style ) => {
// ...split further into key-value pairs
const [ key, ...valueParts ] = style.split( ':' );
const value = valueParts.join( ':' );
return [
key.trim(),
getNormalizedStyleValue( value.trim() ),
];
} );
return fromPairs( pairs );
}
/**
* Attribute-specific equality handlers
*
* @type {Object}
*/
export const isEqualAttributesOfName = {
class: ( actual, expected ) => {
// Class matches if members are the same, even if out of order or
// superfluous whitespace between.
return ! xor( ...[ actual, expected ].map( getTextPiecesSplitOnWhitespace ) ).length;
},
style: ( actual, expected ) => {
return isEqual( ...[ actual, expected ].map( getStyleProperties ) );
},
// For each boolean attribute, mere presence of attribute in both is enough
// to assume equivalence.
...fromPairs( BOOLEAN_ATTRIBUTES.map( ( attribute ) => [ attribute, stubTrue ] ) ),
};
/**
* Given two sets of attribute tuples, returns true if the attribute sets are
* equivalent.
*
* @param {Array[]} actual Actual attributes tuples.
* @param {Array[]} expected Expected attributes tuples.
* @param {Object} logger Validation logger object.
*
* @return {boolean} Whether attributes are equivalent.
*/
export function isEqualTagAttributePairs( actual, expected, logger = createLogger() ) {
// Attributes is tokenized as tuples. Their lengths should match. This also
// avoids us needing to check both attributes sets, since if A has any keys
// which do not exist in B, we know the sets to be different.
if ( actual.length !== expected.length ) {
logger.warning( 'Expected attributes %o, instead saw %o.', expected, actual );
return false;
}
// Convert tuples to object for ease of lookup
const [ actualAttributes, expectedAttributes ] = [ actual, expected ].map( fromPairs );
for ( const name in actualAttributes ) {
// As noted above, if missing member in B, assume different
if ( ! expectedAttributes.hasOwnProperty( name ) ) {
logger.warning( 'Encountered unexpected attribute `%s`.', name );
return false;
}
const actualValue = actualAttributes[ name ];
const expectedValue = expectedAttributes[ name ];
const isEqualAttributes = isEqualAttributesOfName[ name ];
if ( isEqualAttributes ) {
// Defer custom attribute equality handling
if ( ! isEqualAttributes( actualValue, expectedValue ) ) {
logger.warning( 'Expected attribute `%s` of value `%s`, saw `%s`.', name, expectedValue, actualValue );
return false;
}
} else if ( actualValue !== expectedValue ) {
// Otherwise strict inequality should bail
logger.warning( 'Expected attribute `%s` of value `%s`, saw `%s`.', name, expectedValue, actualValue );
return false;
}
}
return true;
}
/**
* Token-type-specific equality handlers
*
* @type {Object}
*/
export const isEqualTokensOfType = {
StartTag: ( actual, expected, logger = createLogger() ) => {
if ( actual.tagName !== expected.tagName ) {
logger.warning( 'Expected tag name `%s`, instead saw `%s`.', expected.tagName, actual.tagName );
return false;
}
return isEqualTagAttributePairs(
...[ actual, expected ].map( getMeaningfulAttributePairs ),
logger
);
},
Chars: isEquivalentTextTokens,
Comment: isEquivalentTextTokens,
};
/**
* Given an array of tokens, returns the first token which is not purely
* whitespace.
*
* Mutates the tokens array.
*
* @param {Object[]} tokens Set of tokens to search.
*
* @return {Object} Next non-whitespace token.
*/
export function getNextNonWhitespaceToken( tokens ) {
let token;
while ( ( token = tokens.shift() ) ) {
if ( token.type !== 'Chars' ) {
return token;
}
if ( ! REGEXP_ONLY_WHITESPACE.test( token.chars ) ) {
return token;
}
}
}
/**
* Tokenize an HTML string, gracefully handling any errors thrown during
* underlying tokenization.
*
* @param {string} html HTML string to tokenize.
* @param {Object} logger Validation logger object.
*
* @return {Object[]|null} Array of valid tokenized HTML elements, or null on error
*/
function getHTMLTokens( html, logger = createLogger() ) {
try {
return new Tokenizer( new DecodeEntityParser() ).tokenize( html );
} catch ( e ) {
logger.warning( 'Malformed HTML detected: %s', html );
}
return null;
}
/**
* Returns true if the next HTML token closes the current token.
*
* @param {Object} currentToken Current token to compare with.
* @param {Object|undefined} nextToken Next token to compare against.
*
* @return {boolean} true if `nextToken` closes `currentToken`, false otherwise
*/
export function isClosedByToken( currentToken, nextToken ) {
// Ensure this is a self closed token
if ( ! currentToken.selfClosing ) {
return false;
}
// Check token names and determine if nextToken is the closing tag for currentToken
if ( nextToken && nextToken.tagName === currentToken.tagName && nextToken.type === 'EndTag' ) {
return true;
}
return false;
}
/**
* Returns true if the given HTML strings are effectively equivalent, or
* false otherwise. Invalid HTML is not considered equivalent, even if the
* strings directly match.
*
* @param {string} actual Actual HTML string.
* @param {string} expected Expected HTML string.
* @param {Object} logger Validation logger object.
*
* @return {boolean} Whether HTML strings are equivalent.
*/
export function isEquivalentHTML( actual, expected, logger = createLogger() ) {
// Tokenize input content and reserialized save content
const [ actualTokens, expectedTokens ] = [ actual, expected ].map(
( html ) => getHTMLTokens( html, logger )
);
// If either is malformed then stop comparing - the strings are not equivalent
if ( ! actualTokens || ! expectedTokens ) {
return false;
}
let actualToken, expectedToken;
while ( ( actualToken = getNextNonWhitespaceToken( actualTokens ) ) ) {
expectedToken = getNextNonWhitespaceToken( expectedTokens );
// Inequal if exhausted all expected tokens
if ( ! expectedToken ) {
logger.warning( 'Expected end of content, instead saw %o.', actualToken );
return false;
}
// Inequal if next non-whitespace token of each set are not same type
if ( actualToken.type !== expectedToken.type ) {
logger.warning( 'Expected token of type `%s` (%o), instead saw `%s` (%o).', expectedToken.type, expectedToken, actualToken.type, actualToken );
return false;
}
// Defer custom token type equality handling, otherwise continue and
// assume as equal
const isEqualTokens = isEqualTokensOfType[ actualToken.type ];
if ( isEqualTokens && ! isEqualTokens( actualToken, expectedToken, logger ) ) {
return false;
}
// Peek at the next tokens (actual and expected) to see if they close
// a self-closing tag
if ( isClosedByToken( actualToken, expectedTokens[ 0 ] ) ) {
// Consume the next expected token that closes the current actual
// self-closing token
getNextNonWhitespaceToken( expectedTokens );
} else if ( isClosedByToken( expectedToken, actualTokens[ 0 ] ) ) {
// Consume the next actual token that closes the current expected
// self-closing token
getNextNonWhitespaceToken( actualTokens );
}
}
if ( ( expectedToken = getNextNonWhitespaceToken( expectedTokens ) ) ) {
// If any non-whitespace tokens remain in expected token set, this
// indicates inequality
logger.warning( 'Expected %o, instead saw end of content.', expectedToken );
return false;
}
return true;
}
/**
* Returns an object with `isValid` property set to `true` if the parsed block
* is valid given the input content. A block is considered valid if, when serialized
* with assumed attributes, the content matches the original value. If block is
* invalid, this function returns all validations issues as well.
*
* @param {string|Object} blockTypeOrName Block type.
* @param {Object} attributes Parsed block attributes.
* @param {string} originalBlockContent Original block content.
* @param {Object} logger Validation logger object.
*
* @return {Object} Whether block is valid and contains validation messages.
*/
export function getBlockContentValidationResult( blockTypeOrName, attributes, originalBlockContent, logger = createQueuedLogger() ) {
const blockType = normalizeBlockType( blockTypeOrName );
let generatedBlockContent;
try {
generatedBlockContent = getSaveContent( blockType, attributes );
} catch ( error ) {
logger.error( 'Block validation failed because an error occurred while generating block content:\n\n%s', error.toString() );
return {
isValid: false,
validationIssues: logger.getItems(),
};
}
const isValid = isEquivalentHTML( originalBlockContent, generatedBlockContent, logger );
if ( ! isValid ) {
logger.error(
'Block validation failed for `%s` (%o).\n\nContent generated by `save` function:\n\n%s\n\nContent retrieved from post body:\n\n%s',
blockType.name,
blockType,
generatedBlockContent,
originalBlockContent
);
}
return {
isValid,
validationIssues: logger.getItems(),
};
}
/**
* Returns true if the parsed block is valid given the input content. A block
* is considered valid if, when serialized with assumed attributes, the content
* matches the original value.
*
* Logs to console in development environments when invalid.
*
* @param {string|Object} blockTypeOrName Block type.
* @param {Object} attributes Parsed block attributes.
* @param {string} originalBlockContent Original block content.
*
* @return {boolean} Whether block is valid.
*/
export function isValidBlockContent( blockTypeOrName, attributes, originalBlockContent ) {
const { isValid } = getBlockContentValidationResult( blockTypeOrName, attributes, originalBlockContent, createLogger() );
return isValid;
}