@wordpress/blocks
Version:
Block API for WordPress.
184 lines • 6.62 kB
TypeScript
import type { Logger, LoggerItem } from './types';
import type { Block, BlockType } from '../../types';
interface HTMLToken {
type: string;
tagName?: string;
chars?: string;
selfClosing?: boolean;
attributes?: Array<[string, string]>;
}
/**
* Returns true if the given string is a valid character reference segment, or
* false otherwise. The text should be stripped of `&` and `;` demarcations.
*
* @param text Text to test.
*
* @return Whether text is valid character reference.
*/
export declare function isValidCharacterReference(text: string): boolean;
/**
* Substitute 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/HEAD/src/entity-parser.ts
*/
export declare class DecodeEntityParser {
/**
* Returns a substitute string for an entity string sequence between `&`
* and `;`, or undefined if no substitution should occur.
*
* @param entity Entity fragment discovered in HTML.
*
* @return Entity substitute value.
*/
parse(entity: string): string | undefined;
}
/**
* Given a specified string, returns an array of strings split by consecutive
* whitespace, ignoring leading or trailing whitespace.
*
* @param text Original text.
*
* @return Text pieces split on whitespace.
*/
export declare function getTextPiecesSplitOnWhitespace(text: string): string[];
/**
* Given a specified string, returns a new trimmed string where all consecutive
* whitespace is collapsed to a single space.
*
* @param text Original text.
*
* @return Trimmed text with consecutive whitespace collapsed.
*/
export declare function getTextWithCollapsedWhitespace(text: string): string;
/**
* 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 token StartTag token.
*
* @return Attribute pairs.
*/
export declare function getMeaningfulAttributePairs(token: HTMLToken): Array<[string, string]>;
/**
* Returns true if two text tokens (with `chars` property) are equivalent, or
* false otherwise.
*
* @param actual Actual token.
* @param expected Expected token.
* @param logger Validation logger object.
*
* @return Whether two text tokens are equivalent.
*/
export declare function isEquivalentTextTokens(actual: HTMLToken, expected: HTMLToken, logger?: Logger): boolean;
/**
* Given a CSS length value, returns a normalized CSS length value for strict equality
* comparison.
*
* @param value CSS length value.
*
* @return Normalized CSS length value.
*/
export declare function getNormalizedLength(value: string): string;
/**
* Given a style value, returns a normalized style value for strict equality
* comparison.
*
* @param value Style value.
*
* @return Normalized style value.
*/
export declare function getNormalizedStyleValue(value: string): string;
/**
* Given a style attribute string, returns an object of style properties.
*
* @param text Style attribute.
*
* @return Style properties.
*/
export declare function getStyleProperties(text: string): Record<string, string>;
/**
* Attribute-specific equality handlers
*/
export declare const isEqualAttributesOfName: Record<string, (actual: string, expected: string) => boolean>;
/**
* Given two sets of attribute tuples, returns true if the attribute sets are
* equivalent.
*
* @param actual Actual attributes tuples.
* @param expected Expected attributes tuples.
* @param logger Validation logger object.
*
* @return Whether attributes are equivalent.
*/
export declare function isEqualTagAttributePairs(actual: Array<[string, string]>, expected: Array<[string, string]>, logger?: Logger): boolean;
/**
* Token-type-specific equality handlers
*/
export declare const isEqualTokensOfType: Record<string, (actual: HTMLToken, expected: HTMLToken, logger?: Logger) => boolean>;
/**
* Given an array of tokens, returns the first token which is not purely
* whitespace.
*
* Mutates the tokens array.
*
* @param tokens Set of tokens to search.
*
* @return Next non-whitespace token.
*/
export declare function getNextNonWhitespaceToken(tokens: HTMLToken[]): HTMLToken | undefined;
/**
* Returns true if the next HTML token closes the current token.
*
* @param currentToken Current token to compare with.
* @param nextToken Next token to compare against.
*
* @return true if `nextToken` closes `currentToken`, false otherwise
*/
export declare function isClosedByToken(currentToken: HTMLToken, nextToken: HTMLToken | undefined): boolean;
/**
* 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 actual Actual HTML string.
* @param expected Expected HTML string.
* @param logger Validation logger object.
*
* @return Whether HTML strings are equivalent.
*/
export declare function isEquivalentHTML(actual: string, expected: string, logger?: Logger): boolean;
/**
* 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 block Block object.
* @param blockTypeOrName Block type or name, inferred from block if not given.
*
* @return Validation results.
*/
export declare function validateBlock(block: Block, blockTypeOrName?: BlockType | string): [boolean, LoggerItem[]];
/**
* 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.
*
* @deprecated Use validateBlock instead to avoid data loss.
*
* @param blockTypeOrName Block type.
* @param attributes Parsed block attributes.
* @param originalBlockContent Original block content.
*
* @return Whether block is valid.
*/
export declare function isValidBlockContent(blockTypeOrName: BlockType | string, attributes: Record<string, unknown>, originalBlockContent: string): boolean;
export {};
//# sourceMappingURL=index.d.ts.map