umberto 3.1.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.1.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": "^37.0.0",
-    "@ckeditor/ckeditor5-dev-ci": "^37.0.0",
-    "@ckeditor/ckeditor5-dev-docs": "^37.0.0",
-    "@ckeditor/ckeditor5-dev-release-tools": "^37.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
 		};
 
@@ -564,7 +571,15 @@ module.exports = class DocDataFactory {
 				}
 
 				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 += ', ';
@@ -724,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 );
 }
 
@@ -746,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 );
@@ -767,6 +766,20 @@ 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.
  *

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/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
@@ -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 );
+			}
 		}
 	}
 
@@ -243,18 +268,37 @@ class TypedocConverter {
 	 */
 	_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 = [];
+
+				if ( type.declaration.children ) {
+					result.push( ...type.declaration.children );
+				}
 
-		return type.declaration.children.map( child => {
+				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 );
 
-			response.name = childSignature.name;
+			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 => {

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/_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/_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/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 )

package/themes/umberto/src/css/_api-subheader.scss

@@ -7,6 +7,8 @@
 	}
 
 	.api-subheader {
+		display: flex;
+
 		&.hidden-loading {
 			display: none;
 		}

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

@@ -29,6 +29,7 @@
 	font-size: u-font-size( -1 );
 	padding: u-spacing( -3 ) u-spacing( -2 ) u-spacing( -3 );
 	border: 1px solid u-color( 'text' );
+	margin-right: 1rem;
 
 	&.badge--has-invert {
 		padding-right: 0;

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

@@ -24,6 +24,15 @@ See: `_api-tree.scss` and `_guide-sdk-tree.scss`. */
 
 	list-style: none;
 
+	&.guide-tree {
+		opacity: 0; //prevents flickering when applying categories fold state
+	}
+
+	&.state-applied {
+		opacity: 1;
+		transition: opacity 0.05s
+	}
+
 	li {
 		position: relative;
 		cursor: pointer;

package/themes/umberto/src/js/_apitree.js

@@ -42,31 +42,23 @@ export function scrollApiTree() {
 	const treeHeight = tree.height();
 	const storageKey = 'side-nav-scroll-top';
 	const sideNavScrollTop = Number( window.localStorage.getItem( storageKey ) );
-	const treeItemClass = 'tree__item__wrapper';
 	const activeTreeItemClass = 'tree__item__wrapper--active';
 	const activeTreeItem = $( `div.side-navigation .${ activeTreeItemClass }` );
-	const treeWrappers = $( `div.side-navigation [class*="${ treeItemClass }"]` );
-	const activeTreeItemIndex = treeWrappers.index( activeTreeItem );
-	let activeTreeItemTop = 25; // 25 is for top padding of side nav.
+	let activeTreeItemTop = 0;
 	const bound = 50; // Offset from top and bottom of side nav.
 
-	// Sum nav tree items heights.
-	treeWrappers.each( function( index ) {
-		if ( activeTreeItemIndex === -1 || index === activeTreeItemIndex ) {
-			return false;
-		}
-
-		activeTreeItemTop += $( this ).height();
-	} );
+	if ( activeTreeItem.length ) {
+		activeTreeItemTop = activeTreeItem[ 0 ].offsetParent ? activeTreeItem[ 0 ].offsetParent.offsetTop : 0;
 
-	if (
-		sideNavScrollTop !== null &&
-		activeTreeItemTop > sideNavScrollTop + bound &&
-		activeTreeItemTop < sideNavScrollTop + treeHeight - bound
-	) {
-		tree.scrollTop( sideNavScrollTop );
-	} else {
-		tree.scrollTop( Math.max( 0, activeTreeItemTop - treeHeight / 2 ) );
+		if (
+			sideNavScrollTop !== null &&
+			activeTreeItemTop > sideNavScrollTop + bound &&
+			activeTreeItemTop < sideNavScrollTop + treeHeight - bound
+		) {
+			tree.scrollTop( sideNavScrollTop );
+		} else {
+			activeTreeItem[ 0 ].scrollIntoView( { block: 'center' } );
+		}
 	}
 
 	tree.scroll( throttle( () => {

package/themes/umberto/src/js/_sidenavigation.js

@@ -5,14 +5,55 @@
 
 export default function sideNavigation() {
 	const folderButtons = Array.from( document.querySelectorAll( '.tree:not(.api-tree) .tree__item--folder' ) );
-	if ( !folderButtons.length ) {
-		return;
+	const guideTreeElement = document.getElementById( 'guidetree' );
+	const foldedClassName = 'tree__item-nested-list--hidden';
+	const activeClassName = '.tree__item__wrapper--active';
+	const localStorageKey = 'foldersState';
+
+	let foldersState = JSON.parse( window.localStorage.getItem( localStorageKey ) );
+	if ( foldersState === null ) {
+		foldersState = {};
 	}
 
 	folderButtons.forEach( btn => {
+		const element = btn.parentNode.nextElementSibling; // Get <ul> element
+		const id = element.getAttribute( 'data-id' );
+
+		applyFolderState( element, foldersState[ id ] );
+		checkForActiveChildren( element, id );
+
 		btn.addEventListener( 'click', function() {
-			// Get <ul> and control it.
-			btn.parentNode.nextElementSibling.classList.toggle( 'tree__item-nested-list--hidden' );
+			element.classList.toggle( foldedClassName );
+			saveFolderState( id, isFolded( element ) );
 		} );
 	} );
+
+	if ( guideTreeElement ) {
+		guideTreeElement.classList.add( 'state-applied' );
+	}
+
+	function applyFolderState( element, folded ) {
+		if ( folded === false ) {
+			element.classList.remove( foldedClassName );
+		}
+		if ( folded === true ) {
+			element.classList.add( foldedClassName );
+		}
+	}
+
+	function saveFolderState( id, state ) {
+		foldersState[ id ] = state;
+		window.localStorage.setItem( localStorageKey, JSON.stringify( foldersState ) );
+	}
+
+	function checkForActiveChildren( element, id ) {
+		if ( element.querySelectorAll( activeClassName ).length > 0 ) {
+			element.classList.remove( foldedClassName );
+			saveFolderState( id, isFolded( element ) );
+		}
+	}
+
+	function isFolded( element ) {
+		return element.classList.contains( foldedClassName );
+	}
 }

package/themes/umberto/src/js/app.js

@@ -44,19 +44,19 @@ window.umberto = {
 $( document ).ready( () => {
 	pageNavigation(); // pageNavigation - needs to be run before filtering initialization.
 	copyMobileApiNavigation(); // copy API Tree into mobile navigation
+	sideNavigation();
+	expandApiTree();
+	scrollApiTree();
 	enableFiltering();
 	setupPrism();
-	expandApiTree();
 	enableCollapsables();
 	hideTogglers();
 	enableAnchors();
 	enableDropdowns();
 	trackArticlePosition();
-	scrollApiTree();
 	setUpFuse();
 	activateDevNames();
 	attachPermalinkListener();
-	sideNavigation();
 	rwdButton();
 	imageModal(); // lightbox for { @img } elements
 	// `sampleCode()` must be called after the `setupPrism()` function.

package/.editorconfig

@@ -1,12 +0,0 @@
-# Configurations to normalize the IDE behavior.
-# http://editorconfig.org/
-
-root = true
-
-[*]
-indent_style = tab
-tab_width = 4
-charset = utf-8
-end_of_line = lf
-trim_trailing_whitespace = true
-insert_final_newline = true

package/.eslintrc.js

@@ -1,41 +0,0 @@
-/**
- * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md.
- */
-
-'use strict';
-
-module.exports = {
-	extends: 'ckeditor5',
-	rules: {
-		'ckeditor5-rules/license-header': [ 'error', { headerLines: [
-			'/**',
-			' * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.',
-			' * For licensing, see LICENSE.md.',
-			' */'
-		] } ]
-	},
-	env: {
-		node: true
-	},
-	ignorePatterns: [
-		'source/**/*.js',
-		'temp/**/*.js',
-		'themes/umberto/source/**/*.js',
-		'tests/src/data-converter/converters/typedoc/fixtures'
-	],
-	overrides: [
-		{
-			files: [ 'scripts/**/*.js' ],
-			globals: {
-				hexo: true
-			}
-		},
-		{
-			files: [ 'themes/**/*.js' ],
-			env: {
-				browser: true
-			}
-		}
-	]
-};