umberto 10.7.4 → 10.7.5

package/CHANGELOG.md

@@ -1,6 +1,17 @@
 Changelog
 =========
 
+## [10.7.5](https://github.com/cksource/umberto/compare/v10.7.4...v10.7.5) (August 13, 2026)
+
+### Bug fixes
+
+* The hierarchy of a class or an interface rendered in the API docs built from Typedoc output now contains the full inheritance chain instead of the first level only. Derived classes, derived interfaces, and implementing classes are also resolved transitively, so the "Subclasses", "Implemented by", and "Implements" lists match the behavior of the JSDoc-based pipeline.
+
+### Other changes
+
+* Unified the rendering of optional properties and parameters in the API documentation in the Gloria theme. Optional members are now marked with the TypeScript question mark suffix, and the separator between a member name and its type no longer contains a space before the colon, matching the TypeScript syntax (for example `options?: Object` instead of `[ options ] : Object`). Previously, optional parameters were wrapped in square brackets and optional properties had the `undefined` type appended to their type lists.
+
+
 ## [10.7.4](https://github.com/cksource/umberto/compare/v10.7.3...v10.7.4) (July 27, 2026)
 
 ### Other changes
@@ -32,22 +43,6 @@ Changelog
 
 * Improved the performance of the documentation build. Pug templates of XML components used in Markdown are now compiled once and reused across pages, instead of being recompiled for every component occurrence. This shortens the page generation phase by about 20%.
 
-
-## [10.7.0](https://github.com/cksource/umberto/compare/v10.6.1...v10.7.0) (July 2, 2026)
-
-### Features
-
-* Enabled MCP install menu in the Kapa widget.
-
-### Bug fixes
-
-* Fixed scrolling to a section in the Gloria theme when navigating to an anchor without a full page reload — for example, changing the anchor in the address bar, using the browser's back/forward buttons, or opening a link to a section on the current page. The target heading is now offset below the sticky header instead of being hidden beneath it.
-* Moved `chokidar` from `devDependencies` to `dependencies`. It is imported at runtime by the file watcher (`src/tasks/watcher.js`), which ships with the package, so it must be installed for consumers. Previously it resolved only by chance through a hoisted copy in the consumer's tree, which fails when the consumer enables pnpm's `enableGlobalVirtualStore` and the package is linked from the global store, outside the consumer's `node_modules`.
-
-### Other changes
-
-* The tabbed content component now sets a `data-tab-label` attribute on each tab panel, carrying the label of its tab. This exposes the label to tools that process the rendered HTML, where it otherwise lives only inside the tab button.
-
 ---
 
 To see all releases, visit the [release page](https://github.com/cksource/umberto/releases).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "10.7.4",
+  "version": "10.7.5",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "type": "module",

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

@@ -89,6 +89,9 @@ export class TypedocConverter {
 			this._convertChild( child );
 		}
 
+		// Resolve full inheritance chains while all doclets still carry their original signatures.
+		this._buildHierarchy();
+
 		// 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.
@@ -101,28 +104,6 @@ export class TypedocConverter {
 				continue;
 			}
 
-			// TODO: Could we get a deep list of all inheritance/derived?
-			// Map parent references of classes and interfaces...
-			if ( 'augmentsNested' in doclet ) {
-				const extendedTypes = doclet._signature.extendedTypes || [];
-
-				doclet.augmentsNested = extendedTypes.flatMap( getHierarchyCallback( this._typeConverter ) );
-			}
-
-			// ...but also, the derived instances...
-			if ( 'descendants' in doclet ) {
-				const extendedBy = doclet._signature.extendedBy || [];
-
-				doclet.descendants = extendedBy.flatMap( getHierarchyCallback( this._typeConverter ) );
-			}
-
-			// ...and implemented interfaces.
-			if ( 'implementsNested' in doclet ) {
-				const implementedTypes = doclet._signature.implementedTypes || [];
-
-				doclet.implementsNested = implementedTypes.flatMap( getHierarchyCallback( this._typeConverter ) );
-			}
-
 			// Unify the `_signature` tuple, so all doclets use the same algorithm.
 			if ( !Array.isArray( doclet._signature ) ) {
 				doclet._signature = [ doclet._signature, doclet._signature ];
@@ -185,6 +166,92 @@ export class TypedocConverter {
 			} );
 	}
 
+	/**
+	 * Fills the `augmentsNested`, `implementsNested`, and `descendants` properties of class and interface doclets
+	 * with full inheritance chains. Typedoc signatures (`extendedTypes`, `implementedTypes`, `extendedBy`) describe
+	 * only the first level of the hierarchy, so ancestor references are followed transitively through the converted
+	 * doclets.
+	 *
+	 * The `augmentsNested` chain continues only through ancestors of the same kind. Ancestors of an interface mixed
+	 * into a class hierarchy (an intersection in `extendedTypes`) extend the list of implemented interfaces instead
+	 * of the inheritance chain rendered on a page. Descendants are calculated by inverting the resolved ancestor
+	 * relations, so both directions of the hierarchy stay consistent.
+	 *
+	 * @protected
+	 */
+	_buildHierarchy() {
+		const docletsByLongname = new Map( this._doclets.map( doclet => [ doclet.longname, doclet ] ) );
+		const hierarchyDoclets = this._doclets.filter( doclet => doclet._signature && 'augmentsNested' in doclet );
+		const relationsCache = new Map();
+
+		const resolveRelations = doclet => {
+			if ( relationsCache.has( doclet ) ) {
+				return relationsCache.get( doclet );
+			}
+
+			const relations = { augmentsNested: [], implementsNested: [] };
+
+			// Fill the cache upfront to break potential reference cycles.
+			relationsCache.set( doclet, relations );
+
+			const collect = ( references, relationName ) => {
+				for ( const reference of references.flatMap( flattenHierarchyReference ) ) {
+					const longname = this._typeConverter.convertReference( reference );
+
+					relations[ relationName ].push( longname );
+
+					const ancestor = docletsByLongname.get( longname );
+
+					if ( !ancestor || !ancestor._signature || !( 'augmentsNested' in ancestor ) ) {
+						continue;
+					}
+
+					const ancestorRelations = resolveRelations( ancestor );
+
+					if ( relationName === 'augmentsNested' && ancestor.kind === doclet.kind ) {
+						relations.augmentsNested.push( ...ancestorRelations.augmentsNested );
+						relations.implementsNested.push( ...ancestorRelations.implementsNested );
+					} else {
+						relations.implementsNested.push( ...ancestorRelations.augmentsNested, ...ancestorRelations.implementsNested );
+					}
+				}
+			};
+
+			collect( doclet._signature.extendedTypes || [], 'augmentsNested' );
+			collect( doclet._signature.implementedTypes || [], 'implementsNested' );
+
+			relations.augmentsNested = [ ...new Set( relations.augmentsNested ) ].filter( name => name !== doclet.longname );
+			relations.implementsNested = [ ...new Set( relations.implementsNested ) ].filter( name => name !== doclet.longname );
+
+			return relations;
+		};
+
+		for ( const doclet of hierarchyDoclets ) {
+			const relations = resolveRelations( doclet );
+
+			doclet.augmentsNested = relations.augmentsNested;
+
+			if ( 'implementsNested' in doclet ) {
+				doclet.implementsNested = relations.implementsNested;
+			}
+
+			doclet.descendants = [];
+		}
+
+		for ( const doclet of hierarchyDoclets ) {
+			const relations = resolveRelations( doclet );
+			const ancestors = new Set( [ ...relations.augmentsNested, ...relations.implementsNested ] );
+
+			for ( const longname of ancestors ) {
+				const ancestor = docletsByLongname.get( longname );
+
+				if ( ancestor && 'descendants' in ancestor && ancestor.descendants ) {
+					ancestor.descendants.push( doclet.longname );
+				}
+			}
+		}
+	}
+
 	/**
 	 * @protected
 	 * @param {BaseReflection} reflection
@@ -964,17 +1031,18 @@ class TypeConverter {
 }
 
 /**
- * @param {TypeConverter} converter
- * @returns {Function}
+ * Flattens an intersection found in a hierarchy relation (for example, `class Foo extends Mixin( Base )` produces
+ * `Base & SomeInterface` in `extendedTypes`) into a list of plain references.
+ *
+ * @param {AvailableTypes} reference
+ * @returns {Array.<ReferenceType>}
  */
-function getHierarchyCallback( converter ) {
-	return reference => {
-		if ( reference.type === 'intersection' ) {
-			return reference.types.map( ref => converter.convertReference( ref ) );
-		}
+function flattenHierarchyReference( reference ) {
+	if ( reference.type === 'intersection' ) {
+		return reference.types;
+	}
 
-		return converter.convertReference( reference );
-	};
+	return [ reference ];
 }
 
 function mapIndexSignatureObject( subItem, index ) {

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

@@ -26,17 +26,19 @@ mixin method( met )
 					code.api-item-heading__code
 						a.doc.b-link( class="member-name" href="#" + id ) #{ met.name }
 
-						//- params ( param1, [param2] )
+						//- params ( param1, param2? )
 						| (
 						if isNonEmptyArray( met.params )
 							each param, index in met.params
 								if param.optional
-									|  [ #{ param.name } ]
+									|  #{ param.name }?
 								else
 									|  #{ param.name }
 								if ( param.subParamsString )
 									//- Allow rendering HTML from the `subParamsString` as it may contain links to other pages.
-									| !{ param.subParamsString }
+									//- The string is prebuilt by the shared `api-builder` with the legacy `[name]`
+									//- convention for optional members, so convert it to the `name?` syntax here.
+									| !{ param.subParamsString.replace( /\[([\w$.]+)\]/g, '$1?' ) }
 								if index < met.params.length - 1
 									|,
 								else

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

@@ -14,21 +14,28 @@ mixin paramsMixin ( params, level, title )
 
             dt
                 code
+                    //- Consecutive piped text lines are joined with a newline, which renders as
+                    //- a space. To keep the TypeScript-style `name?: Type` notation, the colon
+                    //- must live in the same text node as the name.
+                    - const hasTypes = isNonEmptyArray( param.types );
+
                     if isComputedProperty
                         - const [ parentParam, nestedParam ] = param.name.split( '.' );
 
                         | #{ parentParam }
                         i
                             | #{ nestedParam }
-                    else if param.optional
-                        | [ #{ param.name } ]
+                        if hasTypes
+                            | :!{ ' ' }
+                            +type( param.types )
                     else
-                        | #{ param.name }
+                        - const displayName = param.optional ? `${ param.name }?` : param.name;
 
-                    if isNonEmptyArray( param.types )
-                        | :
-                        | !{ ' ' }
-                        +type( param.types )
+                        if hasTypes
+                            | #{ displayName }:!{ ' ' }
+                            +type( param.types )
+                        else
+                            | #{ displayName }
 
             dd
                 if ( param.description )

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

@@ -19,11 +19,11 @@ mixin property( prop )
 			h3
 				div.api-item-heading
 					code.api-item-heading__code
-						a.doc.b-link( class="member-name" href="#" + prop.id ) #{ prop.name }
+						a.doc.b-link( class="member-name" href="#" + prop.id ) #{ prop.optional ? prop.name + '?' : prop.name }
 
 						if isNonEmptyArray( prop.types )
-							|  :!{' '}
-							+type( prop.types, prop.optional )
+							| :!{' '}
+							+type( prop.types )
 					if isNonEmptyArray( prop.badges )
 						+tagWrapper()
 							each badge in prop.badges

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

@@ -1,16 +1,12 @@
 include ./_link-or-text.pug
 
-mixin type( types, isOptional = false )
+mixin type( types )
 	each nameOrObject, index in types
 		+renderType( nameOrObject )
 
 		if index < types.length - 1
 			| !{ ' | ' }
 
-	if ( isOptional && !types.includes( 'undefined' ) )
-		| !{ ' | ' }
-		+renderType( 'undefined' )
-
 //- TODO: Description.
 //-
 //- @param {String|*} inlineObjectOrType

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

@@ -8,7 +8,7 @@ mixin typeParameter( type )
 			//- 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' )
-				| !{' : '}
+				| !{': '}
 				if ( type.isExtending )
 					i !{ 'extends ' }
 				+type( type.value )

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

@@ -18,7 +18,7 @@ if isNonEmptyArray( data.typeParameters )
 								//- 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' )
-									| !{' : '}
+									| !{': '}
 									if ( type.isExtending )
 										i !{ 'extends ' }
 									+type( type.value )