umberto 2.3.1 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "2.3.1",
+  "version": "2.5.0",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [
@@ -56,10 +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-docs": "^32.0.1",
-    "@ckeditor/ckeditor5-dev-release-tools": "^32.0.1",
+    "@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",

package/scripts/filter/after-post-render/fix-code-samples.js

@@ -7,10 +7,22 @@
 
 const { default: cheerio } = require( 'cheerio' );
 
+const regexp = /(?<=>)utf8_encoded_content:([0-9,]+)(?=<\/code><\/pre>)/g;
+const textDecoder = new TextDecoder();
+
 /**
  * Fixes some codeblocks issues.
  */
 hexo.extend.filter.register( 'after_post_render', page => {
+	// Decoding codeblocks inside infobox from UTF-8. See #1122.
+	if ( regexp.test( page.content ) ) {
+		page.content = page.content.replace( regexp, ( match, encodedContent ) => {
+			const decodedContent = textDecoder.decode( new Uint8Array( encodedContent.split( ',' ) ) );
+
+			return decodedContent.replace( /^\n/, '' );
+		} );
+	}
+
 	const $ = cheerio.load( page.content, null, false );
 
 	// This is an attempt to automatically discover code blocks of HTML and add 'html' class if needed.

package/scripts/utils/transforminfobox.js

@@ -7,6 +7,9 @@
 
 const INFO_BOX_REGEXP = /<info-box[^>]*>([\s\S]*?)<\/info-box>/g;
 const INFO_BOX_TYPE_REGEXP = /<info-box\s*(\w*)[^>]*>/;
+const CODEBLOCK_REGEXP_STRING = /```(\S+)?(\n[\s\S]*?)```/g;
+
+const textEncoder = new TextEncoder();
 
 /**
  * Replaces the `<info-box>` element with the HTML `div` element. E.g.:
@@ -61,6 +64,15 @@ function processInfobox( content, hexo ) {
 		content = content.replace( /^\n/, '' );
 		content = content.replace( /\n$/, '' );
 
+		// Encoding codeblocks inside infobox into UTF-8. See #1122.
+		content = content.replace( CODEBLOCK_REGEXP_STRING, ( match, language, content ) => {
+			const encodedContent = textEncoder.encode( content );
+
+			return language ?
+				`<pre class="highlight"><code class="${ language }">utf8_encoded_content:${ encodedContent }</code></pre>` :
+				`<pre class="highlight"><code>utf8_encoded_content:${ encodedContent }</code></pre>`;
+		} );
+
 		let markdownOutput = hexo.render.renderSync( { text: content, engine: 'markdown' } );
 		markdownOutput = markdownOutput.replace( /<\/p>\n/g, '</p>' );
 		markdownOutput = markdownOutput.replace( /\n<p>/g, '<p>' );

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/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/methodparser.js

@@ -33,7 +33,7 @@ module.exports = class MethodParser extends AbstractParser {
 
 				scope: this.getScope( item ),
 				kind: this.getKind( item ),
-				access: this.getVisibility( item ),
+				access: this.getVisibilityIncludingSignature( item, index ),
 				extraId: this.getExtraId( item ),
 				fires: this.getFiredEvents( signature, parentName ),
 				description: this.getComment( signature ),
@@ -60,4 +60,21 @@ module.exports = class MethodParser extends AbstractParser {
 			return doclet;
 		} );
 	}
+
+	/**
+	 * Returns the access type for the item based on its signatures.
+	 *
+	 * @param {TypedocReflection<ConstructorOrMethod>} item
+	 * @param {Number} sourceIndex
+	 * @returns {'public'|'internal'|'protected'|'private'}
+	 */
+	getVisibilityIncludingSignature( item, sourceIndex ) {
+		const signatureVisibility = this.getVisibility( item.signatures[ sourceIndex ] );
+
+		if ( signatureVisibility !== 'public' ) {
+			return signatureVisibility;
+		}
+
+		return this.getVisibility( item );
+	}
 };

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/tasks/build-documentation.js

@@ -22,7 +22,7 @@ const cacheFiles = require( './cache-files' );
 const overwriteApiGuides = require( './overwrite-api-guides' );
 const cacheDir = upath.join( __dirname, '../../temp/cache' );
 const validateLinks = require( './validate-links' );
-const createSitemamp = require( './create-sitemap' );
+const createSitemap = require( './create-sitemap' );
 const buildSnippets = require( './build-snippets' );
 const copyProjectIcons = require( './copy-project-icons' );
 const executeHooks = require( './execute-hooks' );
@@ -269,7 +269,7 @@ module.exports = options => {
 				}
 			}
 
-			return createSitemamp( 'build/docs', hostname, dst, {
+			return createSitemap( 'build/docs', hostname, dst, {
 				excluded: excludedUrls,
 				extraUrlSettings
 			} );

package/themes/umberto/layout/_partial/head.pug

@@ -17,6 +17,9 @@ if ( page[ 'twitter-card' ] || ogConfig.description )
 
 meta( name= 'x-generated-at' content= Date() )
 
+if ( projectLocals.projectVersion )
+	meta( name= 'project-version' content= projectLocals.projectVersion )
+
 if ( mainOg || ( projectLocals && projectLocals.og ) || page[ 'og-description' ] )
 	meta( property='og:title' content= page[ 'og-title' ] || title )
 	if ( ogConfig.description || page[ 'og-description' ] )
@@ -60,7 +63,7 @@ if projectLocals
 if page.isSnippetPage
 	//UMBERTO: SNIPPET: CSS
 
-include google-optimize 
+include google-optimize
 include google-tag-manager
 include google-analytics
 

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

@@ -57,6 +57,7 @@ p.tip {
 
 	&__feedback {
 	  	border-left: 3px solid u-color( 'hint-hint' );
+	  	background-color: rgba( u-color( 'hint-hint' ), .1 );
 	}
 
 	&__warning {
@@ -64,6 +65,11 @@ p.tip {
 		background-color: rgba( u-color( 'hint-warning' ), .1 );
 	}
 
+	&__error {
+		border-left: 3px solid u-color( 'hint-error' );
+		background-color: rgba( u-color( 'hint-error' ), .1 );
+	}
+
 	&_menu-like {
 		ul, ol {
 			list-style: none;

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

@@ -125,11 +125,6 @@ div.code-toolbar {
 	position: relative;
 
 	& > .toolbar {
-		/* The toolbar does not look well on mobiles. There's not enough space. */
-		@include u-responsive-mobile {
-			display: none;
-		}
-
 		position: absolute;
 		top: u-spacing( -2 );
 		right: u-spacing( -2 );

package/themes/umberto/src/css/helpers/_color.scss

@@ -30,7 +30,8 @@ $u-colors: (
 	// Hints
 	'hint-info': #64B5F6,
 	'hint-hint': #AB47BC,
-	'hint-warning': #FF1D00
+	'hint-warning': #FFE600,
+	'hint-error': #FF1D00
 );
 
 @function u-color( $name, $offset: 0% ) {

package/themes/umberto/src/js/_attachpermalinklistener.js

@@ -0,0 +1,38 @@
+/**
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+const latestRegexp = /(?<=\/)latest(?=\/)/;
+
+export default function attachPermalinkListener() {
+	const projectVersionElement = document.querySelector( 'meta[name=project-version]' );
+
+	if ( !projectVersionElement ) {
+		return;
+	}
+
+	const projectVersion = projectVersionElement.getAttribute( 'content' );
+
+	document.addEventListener( 'keypress', event => {
+		if ( event.metaKey ) {
+			return;
+		}
+
+		if ( event.shiftKey ) {
+			return;
+		}
+
+		if ( event.key.toUpperCase() !== 'Y' ) {
+			return;
+		}
+
+		if ( !latestRegexp.test( location.href ) ) {
+			return;
+		}
+
+		const newUrl = location.href.replace( latestRegexp, projectVersion );
+
+		history.replaceState( history.state, document.title, newUrl );
+	} );
+}

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

@@ -26,6 +26,7 @@ import { rwdButton } from './_rwdmenu';
 import imageModal from './_imageModal';
 import showWarningBanner from './_warningbanner';
 import { enableBadgeTooltips, createTooltip } from './_tooltips';
+import attachPermalinkListener from './_attachpermalinklistener';
 
 // Changing documentation theme. To enable, type in the console: `localStorage.setItem( 'theme', 'theme-dark' )`.
 if ( localStorage.getItem( 'theme' ) === 'theme-dark' ) {
@@ -54,6 +55,7 @@ $( document ).ready( () => {
 	scrollApiTree();
 	setUpFuse();
 	activateDevNames();
+	attachPermalinkListener();
 	sideNavigation();
 	rwdButton();
 	imageModal(); // lightbox for { @img } elements