umberto 3.0.0 → 3.2.0

package/README.md

@@ -297,6 +297,10 @@ Use `category: none` for pages not belonging to any category, e.g. 404 page. 404
 
 If no `<h1>` heading is present in a guide, the title will be used to create the guide title automatically. It is recommended to put a `<h1>` heading in a guide and skip this option.
 
+#### folded [optional]
+
+If defined and set to `true`, the category will be folded.
+
 #### slug [optional]
 
 If `slug` is defined, the guide's file name after processing by Umberto will be changed to the slug.
@@ -701,15 +705,11 @@ After generating the changelog, you are able to release the package.
 First, you need to bump the version:
 
 ```bash
-npm run release:bump-version
+npm run release:prepare-packages
 ```
 
-You can also use the `--dry-run` option in order to see what this task does.
-
 After bumping the version, you can publish the changes:
 
 ```bash
-npm run release:publish
+npm run release:publish-packages
 ```
-
-As in the previous task, the `--dry-run` option is also available.

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "umberto",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [
     "scripts",
     "src",
     "themes",
-    ".editorconfig",
-    ".eslintrc.js",
     "hexo-config.json",
     "hexo-shim.js",
-    "scripts-dev/postinstall.js"
+    "README.md",
+    "LICENSE.md",
+    "CHANGELOG.md"
   ],
   "dependencies": {
     "@babel/core": "^7.18.10",
@@ -55,40 +55,10 @@
     "vnu-jar": "^21.10.12",
     "webpack": "^5.74.0"
   },
-  "devDependencies": {
-    "@ckeditor/ckeditor5-dev-bump-year": "^35.0.0",
-    "@ckeditor/ckeditor5-dev-ci": "^35.0.0",
-    "@ckeditor/ckeditor5-dev-docs": "^35.0.0",
-    "@ckeditor/ckeditor5-dev-release-tools": "^35.0.0",
-    "browser-sync": "^2.27.10",
-    "chai": "^4.3.6",
-    "chokidar": "^3.5.3",
-    "eslint": "^8.21.0",
-    "eslint-config-ckeditor5": "^4.0.1",
-    "husky": "^8.0.2",
-    "lint-staged": "^13.0.3",
-    "mocha": "^10.0.0",
-    "mockery": "^2.1.0",
-    "proxyquire": "^2.1.3",
-    "sinon": "^14.0.0",
-    "typescript": "^4.8.4"
-  },
   "engines": {
     "node": ">=16.0.0",
     "npm": ">=5.7.1"
   },
-  "scripts": {
-    "postinstall": "node ./scripts-dev/postinstall.js",
-    "dev:build-single": "node ./scripts-dev/build-single.js",
-    "dev:build-multi": "node ./scripts-dev/build-multi.js",
-    "dev:serve": "node ./scripts-dev/serve.js",
-    "lint": "eslint --quiet '**/*.js'",
-    "test": "mocha tests --recursive",
-    "coverage": "nyc --reporter=lcov --reporter=text-summary --cache false npm run test",
-    "changelog": "node ./scripts-dev/changelog.js",
-    "release:bump-version": "node ./scripts-dev/bump-version.js",
-    "release:publish": "node ./scripts-dev/publish.js"
-  },
   "author": "CKSource (http://cksource.com/)",
   "license": "MIT",
   "homepage": "https://github.com/cksource/umberto",

package/src/api-builder/classes/doc-data-factory.js

@@ -192,16 +192,23 @@ module.exports = class DocDataFactory {
 		// "member-" as a static string must be the same as defined in `addTypedefProperties()` helper in the `@ckeditor/jsdoc-plugins` package.
 		// See: https://github.com/ckeditor/ckeditor5-dev/blob/aa905a702d337db001445efc1036ab2b33069d44/packages/jsdoc-plugins/lib/relation-fixer/addtypedefproperties.js#L95
 		/* eslint-enable max-len */
-		for ( const property of properties ) {
-			if ( doclet.kind == 'typedef' && !property.id ) {
-				property.id = 'member-' + property.name;
-				property.longname = `${ doclet.longname }#${ property.name }`;
+		if ( doclet.kind == 'typedef' ) {
+			for ( const property of properties ) {
+				if ( !property.id ) {
+					property.id = 'member-' + property.name;
+				}
+
+				if ( !property.longname ) {
+					const [ name ] = property.id.split( 'member-' ).filter( Boolean );
+
+					property.longname = `${ doclet.longname }#${ name }`;
+				}
 			}
 		}
 
 		const itemData = {
 			types: getTypes( doclet ),
-			properties: properties.sort( ( a, b ) => a.name <= b.name ? -1 : 1 ),
+			properties: properties.sort( ( a, b ) => sorter( a.name, b.name ) ),
 			augments: augmentsNested
 		};
 
@@ -513,20 +520,26 @@ module.exports = class DocDataFactory {
 	 */
 	_processParams( data = [] ) {
 		const resultParams = data.slice(); // copy data array
-		const parentParams = []; // params which have sub-params; e.g. options
 
-		for ( const item of resultParams ) {
+		// Find properties that may contain nested properties.
+		const parentParams = resultParams.filter( item => {
 			if ( item.params ) {
-				continue;
+				return true;
 			}
 
-			// Parent params are of type 'Object'.
-			for ( const type of item.types ) {
-				if ( type === 'Object' ) {
-					parentParams.push( item );
+			return item.types.some( type => {
+				// An inline callback.
+				if ( type.type && type.type === 'function' ) {
+					return true;
+				}
+
+				if ( typeof type !== 'string' ) {
+					return false;
 				}
-			}
-		}
+
+				return type.toLowerCase() === 'object';
+			} );
+		} );
 
 		// For every parentParam gather its subparams.
 		for ( const parent of parentParams ) {
@@ -535,7 +548,7 @@ module.exports = class DocDataFactory {
 			for ( let i = 0; i < resultParams.length; i++ ) {
 				const item = resultParams[ i ];
 
-				if ( item.name && item.name.indexOf( `${ parent.name }.` ) !== -1 ) {
+				if ( item.name && item.name.includes( `${ parent.name }.` ) ) {
 					subParams.push( item );
 					// remove sub-params from main array, they will be kept under parentParam
 					resultParams.splice( i--, 1 );
@@ -549,8 +562,24 @@ module.exports = class DocDataFactory {
 			if ( parent.params.length > 0 ) {
 				parent.subParamsString = ' = { ';
 
+				if ( parent.types.length === 1 && parent.types[ 0 ].type === 'function' ) {
+					parent.subParamsString += renderInlineCallbackAsObjectProperty( parent.types[ 0 ] );
+
+					if ( subParams.length ) {
+						parent.subParamsString += ', ';
+					}
+				}
+
 				subParams.forEach( ( sub, index ) => {
-					parent.subParamsString += sub.optional ? `[${ sub.name }]` : sub.name;
+					const isComputedProperty = sub.id === 'member-__index';
+
+					if ( isComputedProperty ) {
+						const [ parentParam, nestedParam ] = sub.name.split( '.' );
+
+						parent.subParamsString += `${ parentParam }<i>${ nestedParam }</i>`;
+					} else {
+						parent.subParamsString += sub.optional ? `[${ sub.name }]` : sub.name;
+					}
 
 					if ( index < subParams.length - 1 ) {
 						parent.subParamsString += ', ';
@@ -710,15 +739,7 @@ function sortLongnamesAlphabetically( arr ) {
 				split: splitLongname( item ).name
 			};
 		} )
-		.sort( ( a, b ) => {
-			if ( a.split < b.split ) {
-				return -1;
-			} else if ( a.split > b.split ) {
-				return 1;
-			} else {
-				return 0;
-			}
-		} )
+		.sort( ( a, b ) => sorter( a.split, b.split ) )
 		.map( item => item.entry );
 }
 
@@ -732,15 +753,7 @@ function sortPartsAlphabetically( arr, criteria = [ {} ] ) {
 	for ( const crit of criteria ) {
 		const tmp = arr
 			.filter( item => item[ crit.key ] === crit.value )
-			.sort( ( a, b ) => {
-				if ( a.name < b.name ) {
-					return -1;
-				} else if ( a.name > b.name ) {
-					return 1;
-				} else {
-					return 0;
-				}
-			} );
+			.sort( ( a, b ) => sorter( a.name, b.name ) );
 
 		tmp.forEach( item => {
 			const index = arr.indexOf( item );
@@ -752,3 +765,63 @@ function sortPartsAlphabetically( arr, criteria = [ {} ] ) {
 
 	return result;
 }
+
+function sorter( a, b ) {
+	// Computed property name starts with the "[" character. We want to show them on the top, so let's prepend the name
+	// (only for the sorting purposes) with a space, which ASCII code is less than any other alphanumeric character.
+	if ( a.startsWith( '[' ) ) {
+		a = ' ' + a;
+	}
+
+	if ( b.startsWith( '[' ) ) {
+		b = ' ' + b;
+	}
+
+	return a <= b ? -1 : 1;
+}
+
+/**
+ * This is a JavaScript version of the `renderInlineFunction()` pug mixin.
+ *
+ * See: themes/umberto/layout/_api-docs/_mixin/_type.pug.
+ *
+ * The goal is to render an inline object describing a callable type.
+ *
+ * @param {Object} type
+ * @param {Array.<String>} type.params
+ * @param {Array.<String>|String} type.returns
+ * @param {Boolean} type.isClass
+ * @returns {String}
+ */
+function renderInlineCallbackAsObjectProperty( type ) {
+	const { params, returns, isClass } = type;
+
+	return [
+		// Indicate if a function returns a class.
+		isClass ? 'new' : '',
+
+		// Parameters section.
+		'(',
+		params.map( mapToDocletCallback ).join( ', ' ),
+		')',
+
+		// Returns section.
+		' =&gt; ',
+
+		// Wraps an union in brackets.
+		Array.isArray( returns ) ? '(' : '',
+		Array.isArray( returns ) ? returns.map( mapToDocletCallback ).join( ' | ' ) : mapToDocletCallback( returns ),
+		Array.isArray( returns ) ? ')' : ''
+	].join( '' );
+
+	function mapToDocletCallback( param ) {
+		if ( !param.startsWith( 'module:' ) ) {
+			return param;
+		}
+
+		const href = param.replace( /:|\//g, '_' ).replace( '~', '-' ) + '.html';
+		const value = param.split( '~' )[ 1 ];
+
+		return `<a href="${ href }">${ value }</a>`;
+	}
+}

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

@@ -73,6 +73,16 @@ module.exports = class AbstractParser {
 		return `${ parentName }${ separator }${ item.name }`;
 	}
 
+	/**
+	 * Prepares the name for the computed property.
+	 *
+	 * @param {TypedocReflection<'Index signature'>} item
+	 * @returns {String}
+	 */
+	getComputedName( item ) {
+		return TypedocConverter.getComputedName( item );
+	}
+
 	/**
 	 * Returns the access type for the item.
 	 *
@@ -121,6 +131,7 @@ module.exports = class AbstractParser {
 
 			case 'Accessor':
 			case 'Property':
+			case 'Index signature':
 				return 'member';
 
 			case 'Variable':

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

@@ -0,0 +1,30 @@
+/**
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const PropertyParser = require( './propertyparser' );
+
+module.exports = class ComputedPropertyParser extends PropertyParser {
+	/**
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	canParse( item ) {
+		return item.kindString === 'Index signature';
+	}
+
+	/**
+	 * @param {TypedocReflection<'Index signature'>} item
+	 * @param {String} parentName
+	 * @returns {Object}
+	 */
+	parse( item, parentName ) {
+		return {
+			...super.parse( item, parentName ),
+			name: this.getComputedName( item )
+		};
+	}
+};

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

@@ -25,7 +25,8 @@ module.exports = class ModuleParser extends AbstractParser {
 			name: item.name,
 			longname: this.getLongName( item ),
 			kind: this.getKind( item ),
-			extraId: this.getExtraId( item )
+			extraId: this.getExtraId( item ),
+			file: this.getFile( item )
 		};
 	}
 };

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

@@ -61,6 +61,26 @@ class TypedocConverter {
 		return markdown.render( value ).trim();
 	}
 
+	/**
+	 * Prepares the name for the computed property.
+	 *
+	 * @param {TypedocReflection<'Index signature'>} item
+	 * @returns {String}
+	 */
+	static getComputedName( item ) {
+		if ( item.kindString !== 'Index signature' ) {
+			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;
+
+		return `[${ paramName }: ${ paramType }]`;
+	}
+
 	/**
 	 * @param {Object} projectReflection
 	 * @param {Array.<TypedocReflection>} projectReflection.children
@@ -127,7 +147,7 @@ class TypedocConverter {
 			}
 
 			if ( 'properties' in doclet ) {
-				doclet.properties = this._convertProperties( doclet, setSignature );
+				doclet.properties = this._convertProperties( setSignature );
 			}
 
 			if ( 'typeParameters' in doclet ) {
@@ -177,16 +197,21 @@ class TypedocConverter {
 			}
 		}
 
-		if ( reflection.children ) {
-			if ( doclets ) {
-				parentName = doclets[ 0 ].longname;
-			} else {
-				parentName = '';
+		// 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 : '';
+
+			if ( reflection.children ) {
+				reflection.children.forEach( subItem => {
+					this._convertChild( subItem, parentName );
+				} );
 			}
 
-			reflection.children.forEach( subItem => {
-				this._convertChild( subItem, parentName );
-			} );
+			if ( reflection.indexSignature ) {
+				this._convertChild( reflection.indexSignature, parentName );
+			}
 		}
 	}
 
@@ -202,7 +227,7 @@ class TypedocConverter {
 		}
 
 		return signature.parameters
-			.map( item => {
+			.flatMap( item => {
 				const response = this._convertTypeToJsDoc( item );
 
 				response.name = item.name;
@@ -219,47 +244,80 @@ class TypedocConverter {
 					response.defaultvalue = item.defaultValue;
 				}
 
-				return response;
+				const nestedProperties = this._convertProperties( item );
+
+				if ( !nestedProperties ) {
+					return response;
+				}
+
+				return [
+					response,
+					...nestedProperties.map( nestedProperty => {
+						nestedProperty.name = `${ item.name }.${ nestedProperty.name }`;
+
+						return nestedProperty;
+					} )
+				];
 			} );
 	}
 
 	/**
 	 * @protected
-	 * @param {Object} doclet
 	 * @param {TypedocCallSignature} signature
 	 * @returns {Array|null}
 	 */
-	_convertProperties( doclet, signature ) {
+	_convertProperties( signature ) {
 		const types = signature.type.type === 'union' ? signature.type.types : [ signature.type ];
-		const type = types.find( type => type.declaration && type.declaration.children );
 
-		if ( !type ) {
-			return null;
-		}
+		const properties = types
+			.filter( type => type.declaration )
+			.flatMap( type => {
+				const result = [];
 
-		return type.declaration.children.map( child => {
-			const response = this._convertTypeToJsDoc( child );
+				if ( type.declaration.children ) {
+					result.push( ...type.declaration.children );
+				}
 
-			response.name = child.name;
+				if ( type.declaration.indexSignature ) {
+					result.push( type.declaration.indexSignature );
+				}
+
+				return result;
+			} );
+
+		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 response = this._convertTypeToJsDoc( childSignature );
+
+			if ( child.kindString === 'Index signature' ) {
+				// For computed property (stored as index signature by TypeDoc), explicitly create the `id` key (as `extraId` key).
+				// The `id` is then used to created the `longname` key. Otherwise, the `id` and `longname` keys would be created
+				// automatically later and they would contain computed name in their values.
+				response.extraId = `member-${ childSignature.name }`;
+				response.name = TypedocConverter.getComputedName( childSignature );
+			} else {
+				response.name = childSignature.name;
+			}
 
 			if ( signature.comment && signature.comment.blockTags ) {
 				const atProperty = signature.comment.blockTags.find( blockTag => {
-					return blockTag.tag === '@property' && blockTag.name === child.name;
+					return blockTag.tag === '@property' && blockTag.name === childSignature.name;
 				} );
 
 				if ( atProperty ) {
 					response.description = TypedocConverter.convertComment( atProperty.content );
 				}
-			} else if ( child.comment && child.comment.summary ) {
-				response.description = TypedocConverter.convertComment( child.comment.summary );
+			} else if ( childSignature.comment && childSignature.comment.summary ) {
+				response.description = TypedocConverter.convertComment( childSignature.comment.summary );
 			}
 
-			if ( child.flags.isOptional ) {
+			if ( childSignature.flags.isOptional ) {
 				response.optional = true;
 			}
 
-			if ( child.defaultValue ) {
-				response.defaultvalue = child.defaultValue;
+			if ( childSignature.defaultValue ) {
+				response.defaultvalue = childSignature.defaultValue;
 			}
 
 			return response;
@@ -436,7 +494,7 @@ class TypeConverter {
 				};
 			}
 
-			const type = this.convert( parameter.type );
+			let type = this.convert( parameter.type );
 
 			// To avoid complex type parameters (they are available in typings provided by TypeScript),
 			// let's ignore unions.
@@ -447,6 +505,10 @@ class TypeConverter {
 				};
 			}
 
+			if ( parameter.default ) {
+				type += ` = ${ this.convertIntrinsicType( parameter.default ) }`;
+			}
+
 			return {
 				name: parameter.name,
 				isExtending: true,

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

@@ -14,6 +14,7 @@ const ConstantParser = require( './typedoc/constantparser' );
 const TypeParser = require( './typedoc/typeparser' );
 const FunctionParser = require( './typedoc/functionparser' );
 const PropertyParser = require( './typedoc/propertyparser' );
+const ComputedPropertyParser = require( './typedoc/computedpropertyparser' );
 const MethodParser = require( './typedoc/methodparser' );
 const ConstructorParser = require( './typedoc/constructorparser' );
 const ErrorParser = require( './typedoc/errorparser' );
@@ -45,6 +46,7 @@ module.exports = data => {
 		MethodParser,
 		AccessorParser,
 		PropertyParser,
+		ComputedPropertyParser,
 		EventParser
 	] );
 

package/src/hexo-manager.js

@@ -85,7 +85,16 @@ class HexoManager {
 	hexoInit() {
 		this.isReady = true;
 
-		return this.hexo.init();
+		return this.hexo.init().then( () => {
+			const renderer = this.hexo.render.renderer.get( 'md' );
+
+			// Disable Nunjucks templating language in the Markdown renderer.
+			// See https://github.com/ckeditor/ckeditor5/issues/14189.
+			if ( renderer ) {
+				renderer.disableNunjucks = true;
+				this.hexo.extend.renderer.register( 'md', 'html', renderer );
+			}
+		} );
 	}
 
 	/**

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

@@ -35,7 +35,8 @@ mixin method( met )
 							else
 								|  #{ param.name }
 							if ( param.subParamsString )
-								| #{ param.subParamsString }
+								//- Allow rendering HTML from the `subParamsString` as it may contain links to other pages.
+								| !{ param.subParamsString }
 							if index < met.params.length - 1
 								|,
 							else

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

@@ -10,12 +10,21 @@ mixin paramsMixin ( params, level, title )
 
     dl
         each param in params
+            - const isComputedProperty = param.id === 'member-__index';
+
             dt
                 code
-                    if param.optional
+                    if isComputedProperty
+                        - const [ parentParam, nestedParam ] = param.name.split( '.' );
+
+                        | #{ parentParam }
+                        i
+                            | #{ nestedParam }
+                    else if param.optional
                         | [ #{ param.name } ]
                     else
                         | #{ param.name }
+
                     if isNonEmptyArray( param.types )
                         | :
                         | !{ ' ' }

package/themes/umberto/layout/_api-docs/_mixin/type-parameter.pug

@@ -5,7 +5,7 @@ mixin typeParameter( type )
 		code
 			span !{ type.name }
 
-			//- Most TypeScript types we mark as `object`, as they structure is complex.
+			//- We mark most TypeScript types as `object`, as their structure is complex.
 			//- Hence, it does not really make sense to show that a type extends an unknown `object`.
 			if ( type.value && type.value[ 0 ] !== 'object' )
 				| !{' : '}

package/themes/umberto/layout/_api-docs/_partial/api-subheader.pug

@@ -6,6 +6,9 @@ div(class="api-subheader hidden-loading")
 		if isNonEmptyArray( data.badges )
 			each badge in data.badges
 				+badge( badge )
+		if isNonEmptyArray( data.types )
+			code
+				+type( data.types )
 	nav.api-subheader__navigation
 		if ( isNonEmptyArray( data.configOptions ) || isNonEmptyArray( data.properties ) || isNonEmptyArray( data.methods ) || isNonEmptyArray( data.events ) )
 			ul

package/themes/umberto/layout/_api-docs/_partial/type-parameters.pug

@@ -12,7 +12,7 @@ if isNonEmptyArray( data.typeParameters )
 						code
 							span( class="member-name" ) #{ type.name }
 
-							//- Most TypeScript types we mark as `object`, as they structure is complex.
+							//- We mark most TypeScript types as `object`, as their structure is complex.
 							//- Hence, it does not really make sense to show that a type extends an unknown `object`.
 							if ( type.value && type.value[ 0 ] !== 'object' )
 								| !{' : '}

package/themes/umberto/layout/_api-docs/api-base.pug

@@ -7,8 +7,6 @@ block content
 
     include _partial/api-info-box
 
-    include _partial/types
-
     include _partial/description
 
     != filter

package/themes/umberto/layout/_mixin/nav-tree-level.pug

@@ -29,7 +29,7 @@ mixin navTreeLevel( data, isRoot )
 					each badge in normalizeBadges( data )
 						span( class="tree__item__badge tree__item__badge_" + badge.name data-badge-tooltip=badge.label )
 							span( class="tree__item__badge__text" ) #{ badge.label }
-			ul.tree__item-nested-list
+			ul( class={ "tree__item-nested-list": true, "tree__item-nested-list--hidden": data.folded } data-id=data.id )
 				each item in dataArr
 					//- Categories have a property 'name', guides don't have property 'name'.
 					if item.name

package/themes/umberto/layout/_partial/nav-tree.pug

@@ -5,5 +5,5 @@ include ../_mixin/nav-tree-level
 .side-navigation
 	.side-navigation__wrapper
 		nav.side-navigation__inner
-			ul( class="tree guide-tree" )
+			ul( class="tree guide-tree", id="guidetree" )
 				+navTreeLevel( pageGroup, true )