umberto 2.3.0 → 2.4.0

package/.eslintrc.js

@@ -21,7 +21,8 @@ module.exports = {
 	ignorePatterns: [
 		'source/**/*.js',
 		'temp/**/*.js',
-		'themes/umberto/source/**/*.js'
+		'themes/umberto/source/**/*.js',
+		'tests/src/data-converter/converters/typedoc/fixtures'
 	],
 	overrides: [
 		{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [
@@ -56,9 +56,10 @@
     "webpack": "^5.74.0"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-dev-bump-year": "^32.0.1",
-    "@ckeditor/ckeditor5-dev-ci": "^32.0.1",
-    "@ckeditor/ckeditor5-dev-release-tools": "^32.0.1",
+    "@ckeditor/ckeditor5-dev-bump-year": "^34.0.0",
+    "@ckeditor/ckeditor5-dev-ci": "^34.0.0",
+    "@ckeditor/ckeditor5-dev-docs": "^34.0.0",
+    "@ckeditor/ckeditor5-dev-release-tools": "^34.0.0",
     "browser-sync": "^2.27.10",
     "chai": "^4.3.6",
     "chokidar": "^3.5.3",
@@ -68,7 +69,9 @@
     "lint-staged": "^13.0.3",
     "mocha": "^10.0.0",
     "mockery": "^2.1.0",
-    "sinon": "^14.0.0"
+    "proxyquire": "^2.1.3",
+    "sinon": "^14.0.0",
+    "typescript": "^4.8.4"
   },
   "engines": {
     "node": ">=14.0.0",

package/scripts/filter/after-post-render/insert-error-codes.js

@@ -49,5 +49,7 @@ hexo.extend.filter.register( 'after_post_render', page => {
 		$( this ).attr( 'href', relativeUrlHelper( page.path, hrefPath ) );
 	} );
 
-	page.content = page.content.replace( '<p>{@errors}</p>', $.html() );
+	page.content = page.content.replace( '<p>{@errors}</p>', () => {
+		return $.html();
+	} );
 }, 39 );

package/scripts/utils/transforminfobox.js

@@ -42,8 +42,19 @@ function processInfobox( content, hexo ) {
 
 		// Remove unwanted indentation.
 		const lines = content.split( /\n/ );
-		const indentation = lines.length > 1 ? lines[ 1 ].match( /^\s*/ ) : '';
-		const trimmedLines = lines.map( line => line.replace( new RegExp( `^${ indentation }` ), '' ) );
+		const indentation = lines.length > 1 ? lines[ 1 ].match( /^\s*/ )[ 0 ] : '';
+
+		let pattern;
+
+		// When using spaces as indentation, some editors may mix them with tabs.
+		// In such case, let's try to remove tabs as well. 4 spaces are treat as a single tab character.
+		if ( indentation[ 0 ] === ' ' ) {
+			pattern = new RegExp( `^${ indentation }|${ '\\t'.repeat( Math.ceil( indentation.length / 4 ) ) }` );
+		} else {
+			pattern = new RegExp( `^${ indentation }` );
+		}
+
+		const trimmedLines = lines.map( line => line.replace( pattern, '' ) );
 		content = trimmedLines.join( '\n' );
 
 		// Remove first linebreak and last linebreak.

package/src/api-builder/classes/description-parser.js

@@ -177,9 +177,73 @@ module.exports = class DescriptionParser {
 				member = name;
 			}
 
-			const targetDoclet = findTargetDoclet( this._dataCollection, { module, structure, member, label, query } );
+			let targetDoclet = findTargetDoclet( this._dataCollection, { module, structure, member, label, query } );
 			let replaceToPhrase;
 
+			if ( !targetDoclet && options.parentDoclet ) {
+				const augmentsNested = [
+					// If looking for a property, check if it is defined in a derived class, e.g.,
+					//
+					// ```ts
+					// class A {
+					// 	public foo: any;
+					//
+					// 	/**
+					// 	 * See {@link ~A#foo}.
+					// 	 */
+					// 	public getFoo(): void;
+					// }
+					// class B extends A {
+					// }
+					// ```
+					//
+					// `B` contains the property, so from its perspective, the link is valid.
+					// Let's try to parse it as it would be specified as `~B#foo`.
+					options.parentDoclet.longname,
+
+					// When looking for a structure withing the same module, check parent classes, e.g.,
+					//
+					// ```ts
+					// class A {
+					// 	/**
+					// 	 * See {@link ~A}.
+					// 	 */
+					// 	public getFoo(): void;
+					// }
+					// class B extends A {
+					// }
+					// ```
+					//
+					// `~A` seeing from a module containing the `B` class does not make sense.
+					// Let's try to find the proper doclet in parent classes.
+					...( options.parentDoclet.augmentsNested || [] )
+				];
+
+				targetDoclet = augmentsNested
+					.map( augmentName => {
+						const splitResult = splitLongname( augmentName );
+
+						let structure = [
+							`module:${ splitResult.packageName }`,
+							...splitResult.directoryNames,
+							splitResult.moduleName
+						].join( '/' );
+
+						// When `name` and `className` are equal, we look for a `member` in the `${ structure }~${ className }` doclet.
+						if ( splitResult.name === splitResult.className ) {
+							structure += `~${ splitResult.className }`;
+						}
+
+						return findTargetDoclet( this._dataCollection, {
+							structure,
+							member,
+							label,
+							query
+						} );
+					} )
+					.find( Boolean );
+			}
+
 			if ( targetDoclet ) {
 				let href;
 

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

@@ -203,9 +203,13 @@ module.exports = class AbstractParser {
 			return null;
 		}
 
-		return {
-			url: item.sources[ sourceIndex ].url
-		};
+		const { url } = item.sources[ sourceIndex ];
+
+		if ( !url ) {
+			return null;
+		}
+
+		return { url };
 	}
 
 	/**
@@ -330,6 +334,10 @@ module.exports = class AbstractParser {
 	/**
 	 * Checks if the member contains the `@skipSource` annotation.
 	 *
+	 * Note: The `skipSource` flag can be set to `true` even if the member does not contain the annotation.
+	 * It happens when the member has not specified `file` property. In such a case, Umberto does not know
+	 * where to point to a source and decides to skip generating the "See source" button.
+	 *
 	 * @param {TypedocReflectionMeta} item
 	 * @returns {Boolean}
 	 */

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

@@ -22,6 +22,11 @@ module.exports = class ConstructorParser extends MethodParser {
 	 * @returns {Array.<Object>}
 	 */
 	parse( item, parentName ) {
+		// Absence of sources means that the actual class does not have a constructor.
+		if ( !item.sources ) {
+			return null;
+		}
+
 		const results = super.parse( item, parentName );
 
 		for ( const item of results ) {

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

@@ -50,11 +50,32 @@ module.exports = class PropertyParser extends AbstractParser {
 			deprecated: this.isDeprecated( item ),
 			inherited: !!item.inheritedFrom,
 			see: this.getRelated( item, parentName ),
+			defaultvalue: this.getDefault( item ),
 
 			// This property will be filled in the post-processing phase.
 			type: null
 		};
 	}
+
+	/**
+	 * Returns the default value of an item defined by the `@defaultValue` or `@default` tags.
+	 *
+	 * @param {TypedocReflection} item
+	 * @returns {String}
+	 */
+	getDefault( item ) {
+		if ( !item.comment || !item.comment.blockTags ) {
+			return null;
+		}
+
+		const defaultTag = item.comment.blockTags.find( blockTag => blockTag.tag === '@defaultValue' || blockTag.tag === '@default' );
+
+		if ( !defaultTag ) {
+			return null;
+		}
+
+		return defaultTag.content[ 0 ].text;
+	}
 };
 
 /**

package/src/data-converter/converters/typedoc/typedoc.ts

@@ -144,13 +144,7 @@ export type TypedocCallSignature = TypedocReflectionMeta<'Call signature'> & {
 	inheritedFrom?: Record<string, any>;
 };
 
-export type TypedocTypeDetails = string |
-	{
-		type: 'reference';
-		name: string;
-		id?: number;
-		typeArguments?: Array<TypedocReflectionTypeParameter>;
-	} |
+export type TypedocTypeDetails = string | LiteralOrIntrinsic | Reference | TypeOperator |
 	{
 		type: 'union';
 		types: Array<TypedocReflectionType>;
@@ -159,23 +153,11 @@ export type TypedocTypeDetails = string |
 		type: 'array';
 		elementType: TypedocTypeDetails;
 	} |
-	{
-		type: 'intrinsic';
-		name: string;
-	} |
 	{
 		type: 'indexedAccess';
 		objectType: TypedocTypeDetails;
 		indexType: TypedocTypeDetails;
 	} |
-	{
-		type: 'literal';
-		value: string | number | boolean | null;
-	} |
-	{
-		type: 'intrinsic';
-		name: string;
-	} |
 	{
 		type: 'reflection';
 		declaration: {
@@ -192,6 +174,7 @@ export type TypedocTypeDetails = string |
 	} |
 	{
 		type: 'intersection';
+		types: Array<TypedocReflectionType>;
 	} |
 	{
 		type: 'query';
@@ -201,16 +184,17 @@ export type TypedocTypeDetails = string |
 	} |
 	{
 		type: 'mapped';
-		parameter: {
-			name: string;
-		};
-		templateType: {
-			name: string;
-		};
+		parameter: string;
+		parameterType?: TypeOperator | string;
+		templateType: LiteralOrIntrinsic;
 		optionalModifier?: string;
 	} |
 	{
 		type: 'conditional';
+		checkType: Reference;
+		extendsType: TypedocTypeDetails;
+		trueType: TypedocTypeDetails;
+		falseType: TypedocTypeDetails;
 	} |
 	{
 		type: 'template-literal';
@@ -220,11 +204,6 @@ export type TypedocTypeDetails = string |
 		}>;
 		head: string;
 	} |
-	{
-		type: 'typeOperator';
-		operator: string;
-		target: TypedocTypeDetails;
-	} |
 	{
 		type: 'predicate';
 		targetType: TypedocTypeDetails;
@@ -295,3 +274,26 @@ type TypedocSource = {
 	character: number;
 	url: string;
 };
+
+type Reference = {
+	type: 'reference';
+	name: string;
+	id?: number;
+	typeArguments?: Array<TypedocReflectionTypeParameter>;
+};
+
+type TypeOperator = {
+	type: 'typeOperator';
+	operator: string;
+	target: Reference;
+};
+
+type LiteralOrIntrinsic =
+	{
+		type: 'literal';
+		value: string | number | boolean | null;
+	} |
+	{
+		type: 'intrinsic';
+		name: string;
+	};

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

@@ -74,6 +74,11 @@ class TypedocConverter {
 
 		// Then, when all doclets are specified, let's align types.
 		for ( const doclet of this._doclets ) {
+			// Skip source if the `file` property is not specified.
+			if ( !doclet.file ) {
+				doclet.skipSource = true;
+			}
+
 			// Post-processing is possible only if a doclet contains its original signature.
 			if ( !doclet._signature ) {
 				continue;
@@ -632,19 +637,31 @@ class TypeConverter {
 			return typeReflection.queryType.name;
 		}
 
-		// A modified object type.
 		// See: https://www.typescriptlang.org/docs/handbook/2/mapped-types.html.
 		if ( typeReflection.type === 'mapped' ) {
-			return [
+			const type = [
 				'{',
 				'[',
 				typeReflection.parameter,
-				'in',
-				typeReflection.parameterType.name,
+				'in'
+			];
+
+			if ( typeReflection.parameterType.type === 'typeOperator' ) {
+				type.push(
+					typeReflection.parameterType.operator,
+					this.convertReference( typeReflection.parameterType.target )
+				);
+			} else {
+				type.push( typeReflection.parameterType.name );
+			}
+
+			type.push(
 				']?:', // TODO: Perhaps we should check `typeReflection.optionalModifier`.
 				typeReflection.templateType.name,
 				'}'
-			].join( ' ' );
+			);
+
+			return type.join( ' ' );
 		}
 
 		// A conditional type.

package/themes/umberto/src/css/_top.scss

@@ -173,6 +173,12 @@ $u-rwd-button-size: 24px;
 		}
 	}
 
+	&[data-project^='trial'] {
+		li.top__menu-project-logo a {
+			background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='67' height='67' version='1.1'%3E%3Cpath d='m29.23 0.34908c-1.0911 0-2.1811 0.27713-3.1622 0.83323l-11.488 6.5108-11.382 6.6941c-1.9443 1.1432-3.1458 3.2231-3.1638 5.4787l-0.10493 13.203 0.10493 13.205c0.018017 2.2555 1.2195 4.3355 3.1638 5.4787l11.382 6.6925 11.488 6.5124c1.9623 1.1122 4.3637 1.1122 6.326 0l11.488-6.5124 11.382-6.6925c1.9443-1.1432 3.1458-3.2231 3.1638-5.4787l0.10494-13.205-0.10494-13.203c-0.01802-2.2555-1.2194-4.3355-3.1638-5.4787l-11.382-6.6941-11.488-6.5108c-0.98114-0.55611-2.0727-0.83323-3.1638-0.83323zm-0.22711 12.909 4.6783 14.4h15.142l-12.249 8.9009 4.6783 14.4-12.25-8.8993-12.251 8.8993 4.6799-14.4-12.25-8.9009h15.141zm-0.17384 7.7826-2.9711 8.8664h-9.6135l7.7779 5.4787-2.9711 8.8649 7.7779-5.4787 7.7779 5.4787-2.9711-8.8649 7.7779-5.4787h-9.6135z' fill='%23efbb23' stroke-width='.80191'/%3E%3C/svg%3E");
+		}
+	}
+
 	/* Fix proportions of wider logos (ck5 & ck4). */
 	&[data-project='letters'],
 	&[data-project='cs'],

package/themes/umberto/src/js/_prism.js

@@ -32,6 +32,11 @@ export function setupPrism() {
 			const classList = element.classList.values();
 			const preElement = element.parentElement;
 
+			// Don't highlight the element if it has no parent.
+			if ( !preElement ) {
+				return false;
+			}
+
 			for ( const className of classList ) {
 				preElement.classList.add( `language-${ className }` );
 			}