@wordpress/shortcode 4.37.1-next.ba3aee3a2.0 → 4.38.0

package/src/{index.js → index.ts}

@@ -3,18 +3,34 @@
  */
 import memize from 'memize';
 
+/**
+ * Internal dependencies
+ */
+import type {
+	ShortcodeAttrs,
+	ShortcodeMatch,
+	ShortcodeOptions,
+	Match,
+	ReplaceCallback,
+	ShortcodeInstance,
+} from './types';
+
 export * from './types';
 
 /**
  * Find the next matching shortcode.
  *
- * @param {string} tag   Shortcode tag.
- * @param {string} text  Text to search.
- * @param {number} index Index to start search from.
+ * @param tag   Shortcode tag.
+ * @param text  Text to search.
+ * @param index Index to start search from.
  *
- * @return {import('./types').ShortcodeMatch | undefined} Matched information.
+ * @return Matched information.
  */
-export function next( tag, text, index = 0 ) {
+export function next(
+	tag: string,
+	text: string,
+	index: number = 0
+): ShortcodeMatch | undefined {
 	const re = regexp( tag );
 
 	re.lastIndex = index;
@@ -30,7 +46,7 @@ export function next( tag, text, index = 0 ) {
 		return next( tag, text, re.lastIndex );
 	}
 
-	const result = {
+	const result: ShortcodeMatch = {
 		index: match.index,
 		content: match[ 0 ],
 		shortcode: fromMatch( match ),
@@ -54,17 +70,26 @@ export function next( tag, text, index = 0 ) {
 /**
  * Replace matching shortcodes in a block of text.
  *
- * @param {string}                            tag      Shortcode tag.
- * @param {string}                            text     Text to search.
- * @param {import('./types').ReplaceCallback} callback Function to process the match and return
- *                                                     replacement string.
+ * @param tag      Shortcode tag.
+ * @param text     Text to search.
+ * @param callback Function to process the match and return
+ *                 replacement string.
  *
- * @return {string} Text with shortcodes replaced.
+ * @return Text with shortcodes replaced.
  */
-export function replace( tag, text, callback ) {
+export function replace(
+	tag: string,
+	text: string,
+	callback: ReplaceCallback
+) {
 	return text.replace(
 		regexp( tag ),
-		function ( match, left, $3, attrs, slash, content, closing, right ) {
+		// Let us use spread syntax to capture the arguments object.
+		( ...args: string[] ): string => {
+			const match = args[ 0 ];
+			const left = args[ 1 ];
+			const right = args[ 7 ];
+
 			// If both extra brackets exist, the shortcode has been properly
 			// escaped.
 			if ( left === '[' && right === ']' ) {
@@ -72,7 +97,7 @@ export function replace( tag, text, callback ) {
 			}
 
 			// Create the match object and pass it through the callback.
-			const result = callback( fromMatch( arguments ) );
+			const result = callback( fromMatch( args ) );
 
 			// Make sure to return any of the extra brackets if they weren't used to
 			// escape the shortcode.
@@ -90,12 +115,12 @@ export function replace( tag, text, callback ) {
  * `tag` string, a string or object of `attrs`, a boolean indicating whether to
  * format the shortcode using a `single` tag, and a `content` string.
  *
- * @param {Object} options
+ * @param options Shortcode options.
  *
- * @return {string} String representation of the shortcode.
+ * @return String representation of the shortcode.
  */
-export function string( options ) {
-	return new shortcode( options ).string();
+export function string( options: ShortcodeOptions ): string {
+	return new Shortcode( options ).string();
 }
 
 /**
@@ -114,11 +139,11 @@ export function string( options ) {
  * 6. The closing tag.
  * 7. An extra `]` to allow for escaping shortcodes with double `[[]]`
  *
- * @param {string} tag Shortcode tag.
+ * @param tag Shortcode tag.
  *
- * @return {RegExp} Shortcode RegExp.
+ * @return Shortcode RegExp.
  */
-export function regexp( tag ) {
+export function regexp( tag: string ): RegExp {
 	return new RegExp(
 		'\\[(\\[?)(' +
 			tag +
@@ -142,11 +167,11 @@ export function regexp( tag ) {
  *
  * @param {string} text Serialised shortcode attributes.
  *
- * @return {import('./types').ShortcodeAttrs} Parsed shortcode attributes.
+ * @return {ShortcodeAttrs} Parsed shortcode attributes.
  */
-export const attrs = memize( ( text ) => {
-	const named = {};
-	const numeric = [];
+export const attrs = memize( ( text: string ): ShortcodeAttrs => {
+	const named: Record< string, string | undefined > = {};
+	const numeric: string[] = [];
 
 	// This regular expression is reused from `shortcode_parse_atts()` in
 	// `wp-includes/shortcodes.php`.
@@ -197,12 +222,12 @@ export const attrs = memize( ( text ) => {
  * by `regexp()`. `match` can also be set to the `arguments` from a callback
  * passed to `regexp.replace()`.
  *
- * @param {import('./types').Match} match Match array.
+ * @param match Match array.
  *
- * @return {InstanceType<import('./types').shortcode>} Shortcode instance.
+ * @return Shortcode instance.
  */
-export function fromMatch( match ) {
-	let type;
+export function fromMatch( match: Match ): ShortcodeInstance {
+	let type: 'self-closing' | 'closed' | 'single';
 
 	if ( match[ 4 ] ) {
 		type = 'self-closing';
@@ -212,7 +237,7 @@ export function fromMatch( match ) {
 		type = 'single';
 	}
 
-	return new shortcode( {
+	return new Shortcode( {
 		tag: match[ 2 ],
 		attrs: match[ 3 ],
 		type,
@@ -227,13 +252,27 @@ export function fromMatch( match ) {
  * containing a `tag` string, a string or object of `attrs`, a string indicating
  * the `type` of the shortcode ('single', 'self-closing', or 'closed'), and a
  * `content` string.
- *
- * @type {import('./types').shortcode} Shortcode instance.
  */
-const shortcode = Object.assign(
-	function ( options ) {
-		const { tag, attrs: attributes, type, content } = options || {};
-		Object.assign( this, { tag, type, content } );
+class Shortcode implements ShortcodeInstance {
+	// Instance properties
+	tag: string;
+	type?: 'self-closing' | 'closed' | 'single';
+	content?: string;
+	attrs: ShortcodeAttrs;
+
+	// Static methods
+	static next = next;
+	static replace = replace;
+	static string = string;
+	static regexp = regexp;
+	static attrs = attrs;
+	static fromMatch = fromMatch;
+
+	constructor( options: ShortcodeOptions ) {
+		const { tag, attrs: attributes, type, content } = options;
+		this.tag = tag;
+		this.type = type;
+		this.content = content;
 
 		// Ensure we have a correctly formatted `attrs` object.
 		this.attrs = {
@@ -245,50 +284,46 @@ const shortcode = Object.assign(
 			return;
 		}
 
-		const attributeTypes = [ 'named', 'numeric' ];
-
 		// Parse a string of attributes.
 		if ( typeof attributes === 'string' ) {
 			this.attrs = attrs( attributes );
 			// Identify a correctly formatted `attrs` object.
 		} else if (
-			attributes.length === attributeTypes.length &&
-			attributeTypes.every( ( t, key ) => t === attributes[ key ] )
+			'named' in attributes &&
+			'numeric' in attributes &&
+			attributes.named !== undefined &&
+			attributes.numeric !== undefined
 		) {
-			this.attrs = attributes;
-			// Handle a flat object of attributes.
+			this.attrs = attributes as ShortcodeAttrs;
+			// Handle a flat object of attributes (e.g., { foo: 'bar', baz: 'qux' }).
 		} else {
 			Object.entries( attributes ).forEach( ( [ key, value ] ) => {
-				this.set( key, value );
+				if (
+					typeof value === 'string' ||
+					typeof value === 'undefined'
+				) {
+					this.set( key, value );
+				}
 			} );
 		}
-	},
-	{
-		next,
-		replace,
-		string,
-		regexp,
-		attrs,
-		fromMatch,
 	}
-);
 
-Object.assign( shortcode.prototype, {
 	/**
 	 * Get a shortcode attribute.
 	 *
 	 * Automatically detects whether `attr` is named or numeric and routes it
 	 * accordingly.
 	 *
-	 * @param {(number|string)} attr Attribute key.
+	 * @param attr Attribute key.
 	 *
-	 * @return {string} Attribute value.
+	 * @return Attribute value.
 	 */
-	get( attr ) {
-		return this.attrs[ typeof attr === 'number' ? 'numeric' : 'named' ][
-			attr
-		];
-	},
+	get( attr: string | number ): string | undefined {
+		if ( typeof attr === 'number' ) {
+			return this.attrs.numeric[ attr ];
+		}
+		return this.attrs.named[ attr ];
+	}
 
 	/**
 	 * Set a shortcode attribute.
@@ -296,23 +331,26 @@ Object.assign( shortcode.prototype, {
 	 * Automatically detects whether `attr` is named or numeric and routes it
 	 * accordingly.
 	 *
-	 * @param {(number|string)} attr  Attribute key.
-	 * @param {string}          value Attribute value.
+	 * @param attr  Attribute key.
+	 * @param value Attribute value.
 	 *
-	 * @return {InstanceType< import('./types').shortcode >} Shortcode instance.
+	 * @return Shortcode instance.
 	 */
-	set( attr, value ) {
-		this.attrs[ typeof attr === 'number' ? 'numeric' : 'named' ][ attr ] =
-			value;
+	set( attr: string | number, value: string ): this {
+		if ( typeof attr === 'number' ) {
+			this.attrs.numeric[ attr ] = value;
+		} else {
+			this.attrs.named[ attr ] = value;
+		}
 		return this;
-	},
+	}
 
 	/**
 	 * Transform the shortcode into a string.
 	 *
-	 * @return {string} String representation of the shortcode.
+	 * @return String representation of the shortcode.
 	 */
-	string() {
+	string(): string {
 		let text = '[' + this.tag;
 
 		this.attrs.numeric.forEach( ( value ) => {
@@ -344,7 +382,7 @@ Object.assign( shortcode.prototype, {
 
 		// Add the closing tag.
 		return text + '[/' + this.tag + ']';
-	},
-} );
+	}
+}
 
-export default shortcode;
+export default Shortcode;

package/src/test/{index.js → index.ts}

@@ -7,7 +7,7 @@ describe( 'shortcode', () => {
 	describe( 'next', () => {
 		it( 'should find the shortcode', () => {
 			const result = next( 'foo', 'this has the [foo] shortcode' );
-			expect( result.index ).toBe( 13 );
+			expect( result?.index ).toBe( 13 );
 		} );
 
 		it( 'should find the shortcode with attributes', () => {
@@ -15,7 +15,7 @@ describe( 'shortcode', () => {
 				'foo',
 				'this has the [foo param="foo"] shortcode'
 			);
-			expect( result.index ).toBe( 13 );
+			expect( result?.index ).toBe( 13 );
 		} );
 
 		it( 'should not find shortcodes that are not there', () => {
@@ -33,10 +33,10 @@ describe( 'shortcode', () => {
 
 		it( 'should find the shortcode when told to start looking beyond the start of the string', () => {
 			const result1 = next( 'foo', 'this has the [foo] shortcode', 12 );
-			expect( result1.index ).toBe( 13 );
+			expect( result1?.index ).toBe( 13 );
 
 			const result2 = next( 'foo', 'this has the [foo] shortcode', 13 );
-			expect( result2.index ).toBe( 13 );
+			expect( result2?.index ).toBe( 13 );
 
 			const result3 = next( 'foo', 'this has the [foo] shortcode', 14 );
 			expect( result3 ).toBe( undefined );
@@ -48,7 +48,7 @@ describe( 'shortcode', () => {
 				'this has the [foo] shortcode [foo] twice',
 				14
 			);
-			expect( result.index ).toBe( 29 );
+			expect( result?.index ).toBe( 29 );
 		} );
 
 		it( 'should not find escaped shortcodes', () => {
@@ -66,18 +66,18 @@ describe( 'shortcode', () => {
 
 		it( 'should find shortcodes that are incorrectly escaped by newlines', () => {
 			const result1 = next( 'foo', 'this has the [\n[foo]] shortcode' );
-			expect( result1.index ).toBe( 15 );
+			expect( result1?.index ).toBe( 15 );
 
 			const result2 = next( 'foo', 'this has the [[foo]\n] shortcode' );
-			expect( result2.index ).toBe( 14 );
+			expect( result2?.index ).toBe( 14 );
 		} );
 
 		it( 'should still work when there are not equal amounts of square brackets', () => {
 			const result1 = next( 'foo', 'this has the [[foo] shortcode' );
-			expect( result1.index ).toBe( 14 );
+			expect( result1?.index ).toBe( 14 );
 
 			const result2 = next( 'foo', 'this has the [foo]] shortcode' );
-			expect( result2.index ).toBe( 13 );
+			expect( result2?.index ).toBe( 13 );
 		} );
 
 		it( 'should find the second instances of the shortcode when the first one is escaped', () => {
@@ -85,7 +85,7 @@ describe( 'shortcode', () => {
 				'foo',
 				'this has the [[foo]] shortcode [foo] twice'
 			);
-			expect( result.index ).toBe( 31 );
+			expect( result?.index ).toBe( 31 );
 		} );
 
 		it( 'should not find shortcodes that are not full matches', () => {
@@ -221,13 +221,13 @@ describe( 'shortcode', () => {
 		} );
 
 		it( 'should replace shortcode with a number', () => {
-			const result1 = replace( 'foo', 'hello [foo] world', () => 3 );
+			const result1 = replace( 'foo', 'hello [foo] world', () => '3' );
 			expect( result1 ).toBe( 'hello 3 world' );
 
 			const result2 = replace(
 				'foo',
 				'hello [foo bar=bar baz="baz" qux]delete me[/foo] world',
-				() => 4
+				() => '4'
 			);
 			expect( result2 ).toBe( 'hello 4 world' );
 		} );

package/src/types.ts

@@ -13,6 +13,34 @@ export type ShortcodeAttrs = {
 	numeric: string[];
 };
 
+/**
+ * Shortcode object.
+ */
+export interface Shortcode {
+	/**
+	 * Shortcode tag.
+	 */
+	tag: string;
+
+	/**
+	 * Shortcode attributes.
+	 */
+	attrs: ShortcodeAttrs;
+
+	/**
+	 * Shortcode content.
+	 */
+	content?: string;
+
+	/**
+	 * Shortcode type: `self-closing`, `closed`, or `single`.
+	 */
+	type?: 'self-closing' | 'closed' | 'single';
+}
+
+/**
+ * Shortcode match result.
+ */
 export type ShortcodeMatch = {
 	/**
 	 * Index the shortcode is found at.
@@ -31,7 +59,7 @@ export type ShortcodeMatch = {
 };
 
 /**
- * Shortcode options.
+ * Shortcode options for creating a new shortcode.
  */
 export interface ShortcodeOptions {
 	/**
@@ -56,155 +84,51 @@ export interface ShortcodeOptions {
 }
 
 /**
- * Shortcode object.
+ * Match array from regexp.exec() or arguments from replace callback.
  */
-export interface Shortcode extends ShortcodeOptions {
-	/**
-	 * Shortcode attributes.
-	 */
-	attrs: ShortcodeAttrs;
-}
-
 export type Match =
 	| NonNullable< ReturnType< RegExp[ 'exec' ] > >
-	| Array< string >;
+	| IArguments
+	| ArrayLike< string >;
 
+/**
+ * Callback function for replace operations.
+ */
 export type ReplaceCallback = ( shortcode: Shortcode ) => string;
 
 /**
- * WordPress Shortcode instance.
+ * Shortcode instance returned by the constructor.
  */
-export interface shortcode {
-	new ( options: Partial< ShortcodeOptions > ): Shortcode & {
-		/**
-		 * Transform the shortcode into a string.
-		 *
-		 * @return {string} String representation of the shortcode.
-		 */
-		string: () => string;
-
-		/**
-		 * Get a shortcode attribute.
-		 *
-		 * Automatically detects whether `attr` is named or numeric and routes it
-		 * accordingly.
-		 *
-		 * @param {(number|string)} attr Attribute key.
-		 *
-		 * @return {string} Attribute value.
-		 */
-		get: ( attr: string | number ) => string | undefined;
-
-		/**
-		 * Set a shortcode attribute.
-		 *
-		 * Automatically detects whether `attr` is named or numeric and routes it
-		 * accordingly.
-		 *
-		 * @param {(number|string)} attr  Attribute key.
-		 * @param {string}          value Attribute value.
-		 *
-		 * @return {InstanceType< shortcode >} Shortcode instance.
-		 */
-		set: (
-			attr: string | number,
-			value: string
-		) => InstanceType< shortcode >;
-	};
-
-	/**
-	 * Parse shortcode attributes.
-	 *
-	 * Shortcodes accept many types of attributes. These can chiefly be divided into
-	 * named and numeric attributes:
-	 *
-	 * Named attributes are assigned on a key/value basis, while numeric attributes
-	 * are treated as an array.
-	 *
-	 * Named attributes can be formatted as either `name="value"`, `name='value'`,
-	 * or `name=value`. Numeric attributes can be formatted as `"value"` or just
-	 * `value`.
-	 *
-	 * @param text Serialised shortcode attributes.
-	 *
-	 * @return Parsed shortcode attributes.
-	 */
-	attrs: ( text: string ) => ShortcodeAttrs;
-
-	/**
-	 * Generate a Shortcode Object from a RegExp match.
-	 *
-	 * Accepts a `match` object from calling `regexp.exec()` on a `RegExp` generated
-	 * by `regexp()`. `match` can also be set to the `arguments` from a callback
-	 * passed to `regexp.replace()`.
-	 *
-	 * @param match Match array.
-	 *
-	 * @return  Shortcode instance.
-	 */
-	fromMatch: ( match: Match ) => InstanceType< shortcode >;
-
+export interface ShortcodeInstance extends Shortcode {
 	/**
-	 * Find the next matching shortcode.
-	 *
-	 * @param tag   Shortcode tag.
-	 * @param text  Text to search.
-	 * @param index Index to start search from.
+	 * Transform the shortcode into a string.
 	 *
-	 * @return Matched information.
+	 * @return String representation of the shortcode.
 	 */
-	next: (
-		tag: string,
-		text: string,
-		index?: number
-	) => ShortcodeMatch | undefined;
+	string: () => string;
 
 	/**
-	 * Generate a RegExp to identify a shortcode.
-	 *
-	 * The base regex is functionally equivalent to the one found in
-	 * `get_shortcode_regex()` in `wp-includes/shortcodes.php`.
+	 * Get a shortcode attribute.
 	 *
-	 * Capture groups:
+	 * Automatically detects whether `attr` is named or numeric and routes it
+	 * accordingly.
 	 *
-	 * 1. An extra `[` to allow for escaping shortcodes with double `[[]]`
-	 * 2. The shortcode name
-	 * 3. The shortcode argument list
-	 * 4. The self closing `/`
-	 * 5. The content of a shortcode when it wraps some content.
-	 * 6. The closing tag.
-	 * 7. An extra `]` to allow for escaping shortcodes with double `[[]]`
+	 * @param attr Attribute key.
 	 *
-	 * @param tag Shortcode tag.
-	 *
-	 * @return Shortcode RegExp.
+	 * @return Attribute value.
 	 */
-	regexp: ( tag: string ) => RegExp;
+	get: ( attr: string | number ) => string | undefined;
 
 	/**
-	 * Replace matching shortcodes in a block of text.
-	 *
-	 * @param tag      Shortcode tag.
-	 * @param text     Text to search.
-	 * @param callback Function to process the match and return
-	 *                 replacement string.
-	 *
-	 * @return Text with shortcodes replaced.
-	 */
-	replace: ( tag: string, text: string, callback: ReplaceCallback ) => string;
-
-	/**
-	 * Generate a string from shortcode parameters.
-	 *
-	 * Creates a shortcode instance and returns a string.
+	 * Set a shortcode attribute.
 	 *
-	 * Accepts the same `options` as the `shortcode()` constructor, containing a
-	 * `tag` string, a string or object of `attrs`, a boolean indicating whether to
-	 * format the shortcode using a `single` tag, and a `content` string.
+	 * Automatically detects whether `attr` is named or numeric and routes it
+	 * accordingly.
 	 *
-	 * @param options
+	 * @param attr  Attribute key.
+	 * @param value Attribute value.
 	 *
-	 * @return  String representation of the shortcode.
+	 * @return Shortcode instance.
 	 */
-	string: ( options: ShortcodeOptions ) => string;
+	set: ( attr: string | number, value: string ) => ShortcodeInstance;
 }