umberto 6.1.2 → 7.0.0

package/src/data-converter/converters/typedoc/typedocconverter.js

@@ -6,11 +6,13 @@
 'use strict';
 
 const MarkdownIt = require( 'markdown-it' );
+const ReflectionKind = require( './reflectionkind' );
 const markdown = new MarkdownIt( {
 	html: true
 } );
 
 const ISSUE_URL = 'https://github.com/cksource/umberto/issues/new?assignees=&labels=type:feature,squad:platform';
+const MODULE_INDEX_PATTERN = /^module:(?!icons\b)[\w-]+\/index/;
 
 class TypedocConverter {
 	/**
@@ -28,7 +30,7 @@ class TypedocConverter {
 		 * It may contain an identifier from Typedoc that points to another identifier (a reference linked to another reference).
 		 *
 		 * @protected
-		 * @member {Map.<Number, String|Number>}
+		 * @member {Map.<Number, String>}
 		 */
 		this._moduleMap = new Map();
 
@@ -64,16 +66,14 @@ class TypedocConverter {
 	/**
 	 * Prepares the name for the computed property.
 	 *
-	 * @param {TypedocReflection<'Index signature'>} item
+	 * @param {BaseReflection} item
 	 * @returns {String}
 	 */
 	static getComputedName( item ) {
-		if ( item.kindString !== 'Index signature' ) {
+		if ( item.kind !== ReflectionKind.IndexSignature ) {
 			return item.name;
 		}
 
-		// TypeDoc is able to handle only one (the first found one) index signature.
-		// See: https://github.com/TypeStrong/typedoc/blob/af63d9e4e1/src/lib/converter/factories/index-signature.ts#L20
 		const [ firstParam ] = item.parameters;
 		const paramName = firstParam.name;
 		const paramType = firstParam.type.name;
@@ -82,8 +82,7 @@ class TypedocConverter {
 	}
 
 	/**
-	 * @param {Object} projectReflection
-	 * @param {Array.<TypedocReflection>} projectReflection.children
+	 * @param {ProjectReflection} projectReflection
 	 * @returns {Array.<Object>}
 	 */
 	convertToJsDoc( projectReflection ) {
@@ -153,44 +152,47 @@ class TypedocConverter {
 			if ( 'typeParameters' in doclet ) {
 				// For all doclets, it does not matter whether we process a get or a set signature.
 				// Hence, let's use the first one.
-				doclet.typeParameters = this._typeConverter.convertTypeParameters(
-					// Methods/functions || classes/interfaces/typedefs.
-					getSignature.typeParameter || getSignature.typeParameters
-				);
+				doclet.typeParameters = this._typeConverter.convertTypeParameters( getSignature.typeParameters );
+			}
+
+			// To resolve references from a package entry point (`@module package/index`).
+			// We want to link a reference to its target module.
+			//
+			// Currently, we do not render them in the API docs. However, there are plans to improve
+			// rendering of CKEditor 5 packages (`ckeditor5` and `ckeditor5-premium-features`).
+			// So, let's keep it for the future.
+			if ( '_isReference' in doclet ) {
+				let targetDoclet;
+				let referenceId = getSignature.target;
+
+				// The reference identifier may point to another reference identifier.
+				// The loop is needed to get the target (final) module name.
+				do {
+					targetDoclet = this._doclets.find( item => item.id === referenceId );
+					referenceId = targetDoclet.target;
+				} while ( referenceId );
+
+				doclet.targetDoclet = targetDoclet;
 			}
 
-			// In the end, remove the original signature as it isn't needed anymore.
+			// In the end, remove the helper properties.
+			delete doclet._isReference;
 			delete doclet._signature;
 		}
 
-		return this._doclets;
+		// Index pages are not rendered yet. Hence, we drop all these doclets. Except for icons.
+		return this._doclets
+			.filter( doclet => {
+				return !doclet.longname.match( MODULE_INDEX_PATTERN ) && !doclet.memberof?.match( MODULE_INDEX_PATTERN );
+			} );
 	}
 
 	/**
 	 * @protected
-	 * @param {TypedocReflection} reflection
+	 * @param {BaseReflection} reflection
 	 * @param {String|null} [parentName=null]
 	 */
 	_convertChild( reflection, parentName = null ) {
-		// For unknown reasons, TypeScript or TypeDoc treats all CKEditor 5 icons (except for the first one)
-		// as a reference to the first exported member by a module.
-		// We map them manually to display a proper list of the available doclets.
-		// See: https://github.com/cksource/ckeditor5-internal/issues/3993.
-		if ( parentName === 'module:icons/index' && reflection.kindString === 'Reference' ) {
-			reflection = {
-				...reflection,
-				kind: 32,
-				kindString: 'Variable',
-				flags: {
-					isConst: true
-				},
-				type: {
-					type: 'intrinsic',
-					name: 'string'
-				}
-			};
-		}
-
 		const parser = this._parsers.find( parser => parser.canParse( reflection ) );
 
 		let doclets;
@@ -204,40 +206,42 @@ class TypedocConverter {
 
 			for ( const item of doclets ) {
 				this._doclets.push( item );
+
 				this._moduleMap.set( reflection.id, item.longname );
 			}
 		}
 
-		if ( reflection.kindString === 'Reference' ) {
-			if ( reflection.id !== reflection.target ) {
-				this._moduleMap.set( reflection.id, reflection.target );
-			} else {
-				console.warn( `Reference reflection "${ reflection.name }" points to itself, so it has been skipped.` );
-			}
+		if ( !doclets ) {
+			return;
 		}
 
-		// A computed property is stored in the `indexSignature` key, but we want to convert it in the same way as we do for a "normal"
-		// property. Hence, let's just treat the `indexSignature` as it would be a doclet's child, so the dedicated parser for the
-		// `indexSignature` can prepare a doclet for the computed property.
-		if ( reflection.children || reflection.indexSignature ) {
-			parentName = doclets ? doclets[ 0 ].longname : '';
+		const [ doclet ] = doclets;
+		parentName = doclet.longname;
 
-			if ( reflection.children ) {
-				reflection.children.forEach( subItem => {
-					this._convertChild( subItem, parentName );
-				} );
-			}
+		// A computed property is stored in the `indexSignatures` key, but we want to convert it in the same way as we do for a "normal"
+		// property. Hence, let's just treat the `indexSignatures` as it would be a doclet's child, so the dedicated parser for the
+		// `indexSignatures` can prepare a doclet for the computed property.
+		( reflection.children || [] ).forEach( subItem => {
+			this._convertChild( subItem, parentName );
+		} );
 
-			if ( reflection.indexSignature ) {
-				this._convertChild( reflection.indexSignature, parentName );
-			}
-		}
+		( reflection.indexSignatures || [] ).forEach( ( subItem, index ) => {
+			this._convertChild( mapIndexSignatureObject( subItem, index ), parentName );
+		} );
+
+		// CKEditor 5 events are stored in the `ckeditor5Events` key.
+		( reflection.ckeditor5Events || [] ).forEach( subItem => {
+			this._convertChild( {
+				...subItem,
+				isCKEditor5Event: true
+			}, parentName );
+		} );
 	}
 
 	/**
 	 * @protected
 	 * @param {Object} doclet
-	 * @param {TypedocCallSignature} signature
+	 * @param {CallSignatureReflection} signature
 	 * @returns {Array|null}
 	 */
 	_convertParameters( doclet, signature ) {
@@ -282,43 +286,47 @@ class TypedocConverter {
 
 	/**
 	 * @protected
-	 * @param {TypedocCallSignature} signature
+	 * @param {CallSignatureReflection} signature
 	 * @returns {Array|null}
 	 */
 	_convertProperties( signature ) {
-		const types = signature.type.type === 'union' ? signature.type.types : [ signature.type ];
+		let types;
+
+		// Support for a literal object (`const foo: { /* object literal */ } = ...`).
+		if ( 'children' in signature || 'indexSignatures' in signature ) {
+			types = [
+				{
+					declaration: {
+						children: [
+							...( signature.children || [] ),
+							...( signature.indexSignatures || [] ).map( mapIndexSignatureObject )
+						]
+					}
+				}
+			];
+		} else {
+			types = signature.type.type === 'union' ? signature.type.types : [ signature.type ];
+		}
 
 		const properties = types
 			.filter( type => type.declaration )
 			.flatMap( type => {
-				const result = [];
-
-				if ( type.declaration.children ) {
-					result.push( ...type.declaration.children );
-				}
-
-				if ( type.declaration.indexSignature ) {
-					result.push( type.declaration.indexSignature );
-				}
-
-				return result;
+				return [
+					...( type.declaration.children || [] ),
+					...( type.declaration.indexSignatures || [] ).map( mapIndexSignatureObject )
+				];
 			} );
 
 		return properties.map( child => {
 			// Nested properties cannot be duplicated so we can take the first signature when processing functions.
-			const childSignature = child.kindString === 'Method' ? child.signatures[ 0 ] : child;
+			const childSignature = child.kind === ReflectionKind.Method ? child.signatures[ 0 ] : child;
 			const response = this._convertTypeToJsDoc( childSignature );
 
 			// For all properties, explicitly create the `id` key (as `extraId` key).
 			// The `id` is then used to create the `longname` key. Unfortunately, nested properties are processed manually,
 			// so part of the parser's job must be done here.
 			response.extraId = `member-${ childSignature.name }`;
-
-			if ( child.kindString === 'Index signature' ) {
-				response.name = TypedocConverter.getComputedName( childSignature );
-			} else {
-				response.name = childSignature.name;
-			}
+			response.name = TypedocConverter.getComputedName( childSignature );
 
 			if ( signature.comment && signature.comment.blockTags ) {
 				const atProperty = signature.comment.blockTags.find( blockTag => {
@@ -347,16 +355,30 @@ class TypedocConverter {
 	/**
 	 * @protected
 	 * @param {Object} doclet
-	 * @param {TypedocReflectionType} signature
+	 * @param {CallSignatureReflection} signature
 	 * @returns {Array|null}
 	 */
 	_convertReturnTypes( doclet, signature ) {
 		if ( !signature.type ) {
+			// Temporary solution for the `object` type. Let's create a fake structure that converter understands.
+			if ( signature.kind === ReflectionKind.TypeAlias ) {
+				return [
+					this._convertTypeToJsDoc( {
+						type: {
+							type: 'reflection',
+							declaration: {
+								// Passing non-empty `signatures` would convert it as a callable type.
+								signatures: null
+							}
+						}
+					} )
+				];
+			}
+
 			return null;
 		}
 
 		const response = this._convertTypeToJsDoc( signature );
-
 		const comment = signature.comment || {};
 
 		if ( !comment.blockTags ) {
@@ -374,7 +396,7 @@ class TypedocConverter {
 
 	/**
 	 * @protected
-	 * @param {TypedocReflectionType} parameterReflection
+	 * @param {ParameterReflection} parameterReflection
 	 * @returns {Object}
 	 */
 	_convertTypeToJsDoc( parameterReflection ) {
@@ -422,7 +444,7 @@ class TypeConverter {
 	}
 
 	/**
-	 * @param {TypedocReflectionType} type
+	 * @param {AvailableTypes} type
 	 * @returns {Object|Array.<String>|String|null}
 	 */
 	convert( type ) {
@@ -441,7 +463,7 @@ class TypeConverter {
 	}
 
 	/**
-	 * @param {TypedocTypeDetails|null} type
+	 * @param {AvailableTypes|null} type
 	 * @returns {string|Array}
 	 */
 	convertArray( type ) {
@@ -464,7 +486,7 @@ class TypeConverter {
 	 *
 	 * See: `themes/umberto/<theme name>/layout/_api-docs/_mixin/_type.pug`.
 	 *
-	 * @param {Array.<TypedocReflectionTypeParameter>|null} parameters
+	 * @param {Array.<TypeParameterReflection>|null} parameters
 	 * @returns {Array.<Object>|null}
 	 */
 	convertTypeParameters( parameters ) {
@@ -547,23 +569,15 @@ class TypeConverter {
 	}
 
 	/**
-	 * @param {TypedocTypeDetails} reference
+	 * @param {ReferenceType} reference
 	 * @returns {String}
 	 */
 	convertReference( reference ) {
-		let moduleName;
-		let referenceId = reference.id;
-
-		if ( !referenceId ) {
+		if ( !reference.target ) {
 			return reference.name;
 		}
 
-		// The reference identifier in a module map may point to another reference identifier.
-		// The loop is needed to get the target (final) module name.
-		do {
-			moduleName = this._moduleMap.get( referenceId );
-			referenceId = typeof moduleName === 'number' ? moduleName : null;
-		} while ( referenceId );
+		const moduleName = this._moduleMap.get( reference.target );
 
 		if ( moduleName ) {
 			return moduleName;
@@ -573,7 +587,7 @@ class TypeConverter {
 	}
 
 	/**
-	 * @param {TypedocTypeDetails} parameter
+	 * @param {AvailableTypes} parameter
 	 * @returns {Object}
 	 */
 	convertIndexedAccess( parameter ) {
@@ -593,7 +607,7 @@ class TypeConverter {
 	}
 
 	/**
-	 * @param {TypedocTypeDetails} typeReflection
+	 * @param {LiteralOrIntrinsic} typeReflection
 	 * @returns {String|null|*}
 	 */
 	convertIntrinsicType( typeReflection ) {
@@ -609,7 +623,7 @@ class TypeConverter {
 	}
 
 	/**
-	 * @param {Array.<TypedocReflectionType>} types
+	 * @param {Array.<UnionType>} types
 	 * @returns {Set}
 	 */
 	convertUnion( types ) {
@@ -634,11 +648,11 @@ class TypeConverter {
 	 * to report an issue and providing support for the missing structure.
 	 *
 	 * @protected
-	 * @param {TypedocTypeDetails} typeReflection
+	 * @param {AvailableTypes} typeReflection
 	 * @returns {Object|String|Set|null}
 	 */
 	_convertSingleType( typeReflection ) {
-		// See the `TypedocTypeDetails` type in the `typedoc.ts` file for checking the supported types.
+		// See the `AvailableTypes` type in the `typedoc.ts` file for checking the supported types.
 		//
 		// Results of this function is processed by Pug.
 		// See: `themes/umberto/<theme name>/layout/_api-docs/_mixin/_type.pug`.
@@ -691,7 +705,7 @@ class TypeConverter {
 		if ( typeReflection.type === 'reflection' ) {
 			if ( Array.isArray( typeReflection.declaration.signatures ) ) {
 				const [ signature ] = typeReflection.declaration.signatures;
-				const isClass = signature.kindString === 'Constructor signature';
+				const isClass = signature.kind === ReflectionKind.ConstructorSignature;
 
 				const params = ( signature.parameters || [] )
 					.map( singleType => ( {
@@ -724,7 +738,7 @@ class TypeConverter {
 			return 'tuple';
 		}
 
-		if ( typeReflection.type === 'named-tuple-member' ) {
+		if ( typeReflection.type === 'namedTupleMember' ) {
 			return this.convert( typeReflection.element );
 		}
 
@@ -772,7 +786,7 @@ class TypeConverter {
 		}
 
 		// See: https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html.
-		if ( typeReflection.type === 'template-literal' ) {
+		if ( typeReflection.type === 'templateLiteral' ) {
 			const output = typeReflection.tail.reduce( ( output, [ type, suffix ] ) => {
 				return output + '${ ' + this._convertSingleType( type ) + ' }' + suffix;
 			}, typeReflection.head );
@@ -822,6 +836,16 @@ class TypeConverter {
 			};
 		}
 
+		// Since typedoc@0.28, CKEditor 5 types in unions are represented as `unknown`.
+		// We aim to display a pure string instead of the `unknown` value.
+		// See: http://127.0.0.1:8080/ckeditor5/45.0.0/api/module_engine_conversion_conversion-Conversion.html#function-attributeToAttribute
+		if ( typeReflection.type === 'unknown' ) {
+			return {
+				type: 'raw',
+				value: this.convertIntrinsicType( typeReflection )
+			};
+		}
+
 		// At this stage, the type cannot be converted. Perhaps, we missed something while developing
 		// the conversion. Let's ask users to create a new issue containing the non-supported structure.
 		//
@@ -857,3 +881,10 @@ function getHierarchyCallback( converter ) {
 		return converter.convertReference( reference );
 	};
 }
+
+function mapIndexSignatureObject( subItem, index ) {
+	return {
+		...subItem,
+		name: `${ subItem.name }[${ index }]`
+	};
+}

package/src/data-converter/converters/typedoc/typeparser.js

@@ -6,23 +6,25 @@
 'use strict';
 
 const AbstractParser = require( './abstractparser' );
+const ReflectionKind = require( './reflectionkind' );
 
 module.exports = class TypeParser extends AbstractParser {
 	/**
-	 * @param {TypedocReflectionMeta} item
+	 * @param {BaseReflection} item
 	 * @returns {Boolean}
 	 */
 	canParse( item ) {
-		return item.kindString === 'Type alias';
+		return item.kind === ReflectionKind.TypeAlias;
 	}
 
 	/**
-	 * @param {TypedocReflection<'Type alias'>} item
+	 * @param {LiteralObjectReflection} item
 	 * @param {String} parentName
 	 * @returns {Object}
 	 */
 	parse( item, parentName ) {
 		const result = {
+			id: item.id,
 			name: item.name,
 			memberof: parentName,
 			longname: this.getLongName( item, parentName ),
@@ -40,9 +42,11 @@ module.exports = class TypeParser extends AbstractParser {
 			typeParameters: null
 		};
 
-		// There are two distinct type definitions that are rendered in own way by Umberto: function type and object type.
-		// For function type, its params and return type is displayed. For object, all its properties are shown.
-		const isFunctionType = item.type.declaration && item.type.declaration.signatures;
+		// There are various distinct type definitions that are rendered in own way by Umberto:
+		// 1. a function type - show params and return type.
+		// 2. an object type - show all its properties.
+		// 3. a type alias - show the type name.
+		const isFunctionType = item.type?.declaration?.signatures;
 
 		if ( isFunctionType ) {
 			// Needed for post-processing once all project reflections are converted.

package/src/data-converter/converters/typedoc2umberto.js

@@ -19,6 +19,7 @@ const MethodParser = require( './typedoc/methodparser' );
 const ConstructorParser = require( './typedoc/constructorparser' );
 const ErrorParser = require( './typedoc/errorparser' );
 const EventParser = require( './typedoc/eventparser' );
+const ReferenceParser = require( './typedoc/referenceparser' );
 
 module.exports = data => {
 	const projectReflection = JSON.parse( data );
@@ -33,7 +34,7 @@ module.exports = data => {
 		// Top level. All things belong to a module.
 		ModuleParser,
 
-		// Module's children.
+		// Children of a module.
 		ClassParser,
 		InterfaceParser,
 		FunctionParser,
@@ -41,13 +42,18 @@ module.exports = data => {
 		TypeParser,
 		ErrorParser,
 
-		// Class's and interface's children.
+		// Children of an interface or a class.
 		ConstructorParser,
 		MethodParser,
 		AccessorParser,
 		PropertyParser,
 		ComputedPropertyParser,
-		EventParser
+
+		// Events of an interface or a class.
+		EventParser,
+
+		// Helper for processing a package entry point.
+		ReferenceParser
 	] );
 
 	return typedoc.convertToJsDoc( projectReflection );

package/themes/umberto/layout/gloria/_api-docs/_mixin/_type.pug

@@ -56,6 +56,15 @@ mixin renderComplexStructure( complexType )
 		| !{ ' ' }
 		+renderType( complexType.values )
 
+	//- Raw operator.
+	//-
+	//- Since `typedoc@0.28`, some of known types are translated as `unknown`. To display anything, we treat
+	//- them as a pure string. We wrap it in brackets to avoid confusions when it is a part of the union type.
+	if ( complexType.type === 'raw' && complexType.value )
+		| !{ '( ' }
+		| #{ complexType.value }
+		| !{ ' )' }
+
 	//- An object with type arguments.
 	if ( complexType.type === 'generic' && complexType.name && ( complexType.typeParameters || complexType.typeParameter ) )
 		+renderGenericType( complexType )

package/themes/umberto/layout/umberto/_api-docs/_mixin/_type.pug

@@ -56,6 +56,15 @@ mixin renderComplexStructure( complexType )
 		| !{ ' ' }
 		+renderType( complexType.values )
 
+	//- Raw operator.
+	//-
+	//- Since `typedoc@0.28`, some of known types are translated as `unknown`. To display anything, we treat
+	//- them as a pure string. We wrap it in brackets to avoid confusions when it is a part of the union type.
+	if ( complexType.type === 'raw' && complexType.value )
+		| !{ '( ' }
+		| #{ complexType.value }
+		| !{ ' )' }
+
 	//- An object with type arguments.
 	if ( complexType.type === 'generic' && complexType.name && ( complexType.typeParameters || complexType.typeParameter ) )
 		+renderGenericType( complexType )

package/themes/umberto/src/gloria/js/_codeswitcherbuttons.js

@@ -100,11 +100,11 @@ export function createCodeSwitcherButtons() {
 
 		const selfHostedButton = createButton( 'Self-hosted (npm)', activeType === type.selfHosted );
 
-		selfHostedButton.setAttribute( 'title', 'Self-hosted shows imports for installations using npm or ZIP setups.' );
+		selfHostedButton.setAttribute( 'title', 'Show import snippets for npm and ZIP setups.' );
 
 		const cloudButton = createButton( 'Cloud (CDN)', activeType === type.cloud );
 
-		cloudButton.setAttribute( 'title', 'Cloud shows imports for installations using CDN setups.' );
+		cloudButton.setAttribute( 'title', 'Show import snippets for a CDN setup.' );
 
 		const switcherToolbar = switcher.querySelector( `.${ codeSwitcherToolbarClass }` );
 

package/themes/umberto/src/umberto/js/_codeswitcherbuttons.js

@@ -100,11 +100,11 @@ export function createCodeSwitcherButtons() {
 
 		const selfHostedButton = createButton( 'Self-hosted (npm)', activeType === type.selfHosted );
 
-		selfHostedButton.setAttribute( 'title', 'Self-hosted shows imports for installations using npm or ZIP setups.' );
+		selfHostedButton.setAttribute( 'title', 'Show import snippets for npm and ZIP setups.' );
 
 		const cloudButton = createButton( 'Cloud (CDN)', activeType === type.cloud );
 
-		cloudButton.setAttribute( 'title', 'Cloud shows imports for installations using CDN setups.' );
+		cloudButton.setAttribute( 'title', 'Show import snippets for a CDN setup.' );
 
 		const switcherToolbar = switcher.querySelector( `.${ codeSwitcherToolbarClass }` );