umberto 10.2.0 → 10.3.0

package/CHANGELOG.md

@@ -1,6 +1,15 @@
 Changelog
 =========
 
+## [10.3.0](https://github.com/cksource/umberto/compare/v10.2.0...v10.3.0) (April 3, 2026)
+
+### Features
+
+* Added support for displaying and filtering experimental API items in TypeDoc-based API docs.
+
+  Experimental annotations now appear in page headers and member listings, and can be toggled with the API filters.
+
+
 ## [10.2.0](https://github.com/cksource/umberto/compare/v10.1.4...v10.2.0) (April 2, 2026)
 
 ### Features
@@ -38,13 +47,6 @@ Changelog
 
 * Removed unmaintained `hexo-renderer-markdown-it-plus` and `@ckeditor/jsdoc-plugins` dependencies by replacing them with maintained and local implementations, resolving the reported `markdown-it`-related vulnerabilities in Umberto's dependency tree.
 
-
-## [10.1.1](https://github.com/cksource/umberto/compare/v10.1.0...v10.1.1) (March 4, 2026)
-
-### Bug fixes
-
-* Fixed a deprecation warning displayed during documentation builds by migrating Sass compilation to the modern Dart Sass JavaScript API. The `legacy-js-api` warning is no longer emitted.
-
 ---
 
 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.2.0",
+  "version": "10.3.0",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "type": "module",

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

@@ -62,6 +62,7 @@ export class DocDataFactory {
 			access: doclet.access,
 			inherited: doclet.mixed ? false : doclet.inherited,
 			mixed: doclet.mixed,
+			experimental: doclet.experimental || false,
 			deprecated: doclet.deprecated,
 			since: doclet.since,
 			file: doclet.file,
@@ -264,6 +265,7 @@ export class DocDataFactory {
 	 */
 	getClassFull( doclet ) {
 		const classMembersCollection = this._dataCollection.get( `memberof:${ doclet.longname }` );
+		const base = this._getBase( doclet, { headingDecreaseLevel: 2 } );
 		const configOptions = classMembersCollection.get( 'cfg' );
 		const properties = classMembersCollection.get( 'member' );
 		const methods = classMembersCollection.get( 'function' );
@@ -328,7 +330,7 @@ export class DocDataFactory {
 		augmentsNested.unshift( doclet.longname );
 		augmentsNested.reverse();
 
-		return Object.assign( this._getBase( doclet, { headingDecreaseLevel: 2 } ), {
+		return Object.assign( base, {
 			configOptions: configOptionsProcessed,
 			properties: propertiesProcessed,
 			staticProperties,
@@ -644,6 +646,13 @@ function prepareBadges( item, context ) {
 		badges.push( deprecatedBadge );
 	}
 
+	if ( item.experimental ) {
+		badges.push( {
+			class: 'cyan badge--experimental',
+			text: 'experimental'
+		} );
+	}
+
 	if ( item.chainable ) {
 		badges.push( {
 			class: 'green',
@@ -724,7 +733,6 @@ function prepareBadges( item, context ) {
 
 	return badges;
 }
-
 function sortLongnamesAlphabetically( arr ) {
 	if ( !arr || !arr.length ) {
 		return;

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

@@ -370,6 +370,20 @@ export class AbstractParser {
 		return false;
 	}
 
+	/**
+	 * Checks if the member is marked as `experimental` one.
+	 *
+	 * @param {BaseReflection} item
+	 * @returns {Boolean}
+	 */
+	isExperimental( item ) {
+		if ( item.comment && item.comment.modifierTags ) {
+			return item.comment.modifierTags.some( tag => tag === '@experimental' );
+		}
+
+		return false;
+	}
+
 	/**
 	 * Checks if the member is marked by the `@deprecated` JSDoc tag.
 	 *

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

@@ -53,6 +53,7 @@ export class AccessorParser extends AbstractParser {
 			description: this.getComment( getSignature || setSignature ),
 			file: this.getFile( item ),
 			skipSource: this.shouldSkipSource( getSignature || setSignature ),
+			experimental: this.isExperimental( getSignature || setSignature ),
 			deprecated: this.isDeprecated( getSignature || setSignature ),
 			inherited: !!item.inheritedFrom,
 

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

@@ -37,6 +37,7 @@ export class ClassParser extends AbstractParser {
 			description: this.getComment( item ),
 			file: this.getFile( item ),
 			skipSource: this.shouldSkipSource( item ),
+			experimental: this.isExperimental( item ),
 			deprecated: this.isDeprecated( item ),
 
 			// Properties specified below will be mapped to module names once the entire project is transformed.

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

@@ -35,6 +35,7 @@ export class ConstantParser extends AbstractParser {
 			extraId: `constant-${ item.name }`,
 			file: this.getFile( item ),
 			skipSource: this.shouldSkipSource( item ),
+			experimental: this.isExperimental( item ),
 			description: this.getComment( item ),
 			deprecated: this.isDeprecated( item ),
 

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

@@ -38,6 +38,7 @@ export class EventParser extends AbstractParser {
 			description: this.getComment( item ),
 			file: this.getFile( item ),
 			skipSource: this.shouldSkipSource( item ),
+			experimental: this.isExperimental( item ),
 			deprecated: this.isDeprecated( item ),
 			inherited: !!item.inheritedFrom,
 			see: this.getRelated( item, parentName ),

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

@@ -38,6 +38,7 @@ export class FunctionParser extends AbstractParser {
 				description: this.getComment( signature ),
 				file: this.getFile( item, index ),
 				skipSource: this.shouldSkipSource( signature ),
+				experimental: this.isExperimental( signature ),
 				deprecated: this.isDeprecated( signature ),
 				see: this.getRelated( signature, parentName ),
 

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

@@ -36,6 +36,7 @@ export class InterfaceParser extends AbstractParser {
 			description: this.getComment( item ),
 			file: this.getFile( item ),
 			skipSource: this.shouldSkipSource( item ),
+			experimental: this.isExperimental( item ),
 			deprecated: this.isDeprecated( item ),
 
 			typeParameters: null,

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

@@ -39,6 +39,7 @@ export class MethodParser extends AbstractParser {
 				description: this.getComment( signature ),
 				file: this.getFile( item, index ),
 				skipSource: this.shouldSkipSource( signature ),
+				experimental: this.isExperimental( signature ),
 				deprecated: this.isDeprecated( signature ),
 				inherited: !!signature.inheritedFrom,
 				see: this.getRelated( signature, parentName ),

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

@@ -40,6 +40,7 @@ export class PropertyParser extends AbstractParser {
 			description: this.getComment( item ),
 			file: this.getFile( item ),
 			skipSource: this.shouldSkipSource( item ),
+			experimental: this.isExperimental( item ),
 			deprecated: this.isDeprecated( item ),
 			inherited: !!item.inheritedFrom,
 			see: this.getRelated( item, parentName ),

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

@@ -32,6 +32,7 @@ export class TypeParser extends AbstractParser {
 			extraId: this.getExtraId( item ),
 			file: this.getFile( item ),
 			skipSource: this.shouldSkipSource( item ),
+			experimental: this.isExperimental( item ),
 			description: this.getComment( item ),
 			deprecated: this.isDeprecated( item ),
 			firedBy: this.getFiredBy( item, parentName ),

package/src/helpers/create-filtering-data-attribs.js

@@ -28,5 +28,9 @@ export const createFilteringDataAttribs = item => {
 		attrData[ 'data-deprecated' ] = 'true';
 	}
 
+	if ( item.experimental ) {
+		attrData[ 'data-experimental' ] = 'true';
+	}
+
 	return attrData;
 };

package/themes/umberto/layout/gloria/_api-docs/_header/index.pug

@@ -37,6 +37,8 @@ mixin apiHeader( config )
 							+checkbox({ id:'f7', name: 'name4', className: 'js-api-filter-checkbox', label: 'Internal', value: 'internal', expanded: true })
 					+dropdown-item({ narrow: true })
 						+checkbox({ id:'f5', name: 'name7', className: 'js-api-filter-checkbox', label: 'Deprecated', value: 'deprecated', expanded: true, checked: true })
+					+dropdown-item({ narrow: true })
+						+checkbox({ id:'f8', name: 'name8', className: 'js-api-filter-checkbox', label: 'Experimental', value: 'experimental', expanded: true, checked: true })
 
 			+button({
 				icon: 'unordered-list',

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

@@ -0,0 +1,6 @@
+mixin badgeTag( badge, options = {} )
+	- const iconNameByBadgeText = { private: 'lock', observable: 'eye', experimental: 'experiment' };
+	- const iconName = iconNameByBadgeText[ badge.text ] || null;
+	- const linkTo = badge && badge.linkTo ? badge.linkTo : false;
+	- const className = [ options.className || '', linkTo ? 'tag--link' : '', badge.text == 'experimental' ? 'tag--experimental' : '' ].filter( Boolean ).join( ' ' );
+	+tag({ label: badge.text, icon: iconName, iconSize: options.iconSize || 'base', href: linkTo, className })

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

@@ -1,5 +1,6 @@
 include ./_link-or-text.pug
 include ./_badge.pug
+include ./_badge-tag.pug
 include ./_dev-names.pug
 include ./_api-see-source.pug
 include ../../_components/icon/index
@@ -22,10 +23,7 @@ mixin classItem( item )
 					if isNonEmptyArray( item.badges )
 						+tagWrapper()
 							each badge in item.badges
-								- const iconName = badge.text == 'private' ? 'lock' : badge.text == 'observable' ? 'eye' : null;
-								- const linkTo = badge && badge.linkTo ? badge.linkTo : null;
-								- const linkClassName = linkTo ? 'tag--link' : '';
-								+tag({ label: badge.text, icon: iconName, iconSize: 'sm', href: linkTo, className: linkClassName })
+								+badgeTag( badge, { iconSize: 'sm' } )
 
 		+devNames( item.longname )
 

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

@@ -1,4 +1,5 @@
 include _badge
+include _badge-tag.pug
 include _type
 include _params
 include _return
@@ -52,10 +53,7 @@ mixin method( met )
 					if isNonEmptyArray( met.badges )
 						+tagWrapper()
 							each badge in met.badges
-								- const iconName = badge.text == 'private' ? 'lock' : badge.text == 'observable' ? 'eye' : null;
-								- const linkTo = badge && badge.linkTo ? badge.linkTo : null;
-								- const linkClassName = linkTo ? 'tag--link' : '';
-								+tag({ label: badge.text, icon: iconName, iconSize: 'sm', href: linkTo, className: linkClassName })
+								+badgeTag( badge, { iconSize: 'sm' } )
 
 		+devNames( met.longname, met.label )
 

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

@@ -1,6 +1,7 @@
 include _params
 include ./_type.pug
 include ./_badge.pug
+include ./_badge-tag.pug
 include ./_dev-names.pug
 include ./_api-see-source.pug
 include ./_related.pug
@@ -26,10 +27,7 @@ mixin property( prop )
 					if isNonEmptyArray( prop.badges )
 						+tagWrapper()
 							each badge in prop.badges
-								- const iconName = badge.text == 'private' ? 'lock' : badge.text == 'observable' ? 'eye' : null;
-								- const linkTo = badge && badge.linkTo ? badge.linkTo : null;
-								- const linkClassName = linkTo ? 'tag--link' : '';
-								+tag({ label: badge.text, icon: iconName, iconSize: 'sm', href: linkTo, className: linkClassName })
+								+badgeTag( badge, { iconSize: 'sm' } )
 
 		+devNames( prop.longname )
 
@@ -54,4 +52,3 @@ mixin property( prop )
 
 				if isNonEmptyArray( prop.see )
 					+related( prop.see )
-

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

@@ -38,3 +38,7 @@ div( class="notice notice__filter api-props-filter hidden-loading" )
 				input( type="checkbox" id="f5" value="deprecated" )
 				label( for="f5" )
 					span( class="badge badge--red" ) Deprecated
+			li
+				input( type="checkbox" id="f8" value="experimental" checked )
+				label( for="f8" )
+					span( class="badge badge--cyan" ) Experimental

package/themes/umberto/layout/gloria/_api-docs/_subheader/_style.scss

@@ -2,4 +2,11 @@
 .api-subheader {
 	width: 100%;
 	margin-top: var(--spacing-2);
+
+	&__badges {
+		display: flex;
+		align-items: center;
+		flex-wrap: wrap;
+		gap: var(--spacing-2);
+	}
 }

package/themes/umberto/layout/gloria/_api-docs/_subheader/index.pug

@@ -1,10 +1,14 @@
 include ../_mixin/_badge
+include ../_mixin/_badge-tag.pug
 
 mixin apiSubheader()
 	- const iconName = "api-" + data.kind.toLowerCase();
 	- const iconClassName = "api-icon api-icon--" + data.kind.toLowerCase();
 	- const tagClassName = "tag--api tag--api-" + data.kind.toLowerCase();
+	- const experimentalBadge = isNonEmptyArray( data.badges ) ? data.badges.find( badge => badge.text == 'experimental' ) : null;
 
 	div(class="api-subheader hidden-loading")
 		div.api-subheader__badges
 			+tag({ label: data.kind, icon : iconName, className: tagClassName })
+			if experimentalBadge
+				+badgeTag( experimentalBadge )

package/themes/umberto/layout/gloria/_components/tag/_style.scss

@@ -20,6 +20,18 @@
 		}
 	}
 
+	&--experimental {
+		color: var(--color-cyan-600);
+		border-color: var(--color-cyan-600);
+		background-color: var(--color-cyan-50);
+
+		&.tag--link {
+			&:hover {
+				background-color: var(--color-cyan-100);
+			}
+		}
+	}
+
 	&__icon {
 
 		+ .tag__text {

package/themes/umberto/layout/gloria/theme.pug

@@ -191,6 +191,8 @@ div
 				+checkbox({ id:'f5', name: 'name7', label: 'Deprecated', value: 'deprecated', expanded: true })
 			+dropdown-item()
 				+checkbox({ id:'f7', name: 'name4', label: 'Internal', value: 'internal', expanded: true })
+			+dropdown-item()
+				+checkbox({ id:'f8', name: 'name8', label: 'Experimental', value: 'experimental', expanded: true, checked: true })
 			+dropdown-item()
 				+checkbox({ id:'f6', name: 'name3', label: 'Mixed', value: 'mixed', expanded: true })
 

package/themes/umberto/layout/umberto/_api-docs/_partial/filter.pug

@@ -38,3 +38,7 @@ div( class="notice notice__filter api-props-filter hidden-loading" )
 				input( type="checkbox" id="f5" value="deprecated" )
 				label( for="f5" )
 					span( class="badge badge--red" ) Deprecated
+			li
+				input( type="checkbox" id="f8" value="experimental" checked )
+				label( for="f8" )
+					span( class="badge badge--cyan" ) Experimental

package/themes/umberto/src/gloria/js/modules/api-filter.js

@@ -139,21 +139,23 @@ export class ApiFilter extends BaseComponent {
 	 * Sets the initial state of the API filter into local storage when there is no set yet.
 	 */
 	setInitialApiFilterState() {
-		const { apiFilterState } = this.state;
 		const { filterDropdown } = this.elements;
+		const apiFilterState = { ...this.state.apiFilterState };
 
-		if ( Object.keys( apiFilterState ).length === 0 ) {
-			Array.from( filterDropdown.querySelectorAll( '.js-api-filter-checkbox input' ) ).forEach( input => {
-				const isChecked = input.checked;
-				const filterType = input.value;
+		Array.from( filterDropdown.querySelectorAll( '.js-api-filter-checkbox input' ) ).forEach( input => {
+			const isChecked = input.checked;
+			const filterType = input.value;
 
-				this.saveApiFilterState( filterType, isChecked );
-			} );
-		}
+			if ( apiFilterState[ filterType ] === undefined ) {
+				apiFilterState[ filterType ] = isChecked;
+			}
+		} );
+
+		window.localStorage.setItem( API_FILTER_LOCAL_STORAGE_KEY, JSON.stringify( apiFilterState ) );
 
 		this.setState( {
-			apiFilterState: JSON.parse( localStorage.getItem( API_FILTER_LOCAL_STORAGE_KEY ) ) || {},
-			activeFilters: Object.keys( this.state.apiFilterState ).filter( key => this.state.apiFilterState[ key ] )
+			apiFilterState,
+			activeFilters: Object.keys( apiFilterState ).filter( key => apiFilterState[ key ] )
 		} );
 	}
 
@@ -163,14 +165,21 @@ export class ApiFilter extends BaseComponent {
 	initialApplyApiFilterState() {
 		const { apiFilterState } = this.state;
 		const { filterDropdown } = this.elements;
+		const activeFilters = [];
 
 		Array.from( filterDropdown.querySelectorAll( '.js-api-filter-checkbox input' ) ).forEach( input => {
 			const isChecked = input.checked;
 			const filterType = input.value;
 
 			input.checked = apiFilterState[ filterType ] !== undefined ? apiFilterState[ filterType ] : isChecked;
+
+			if ( input.checked ) {
+				activeFilters.push( filterType );
+			}
 		} );
 
+		this.setState( { activeFilters } );
+
 		// this.dispatchInitialFolderStateDoneEvent();
 	}
 

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

@@ -51,6 +51,7 @@
 	@include badge( 'red' );
 	@include badge( 'orange' );
 	@include badge( 'purple' );
+	@include badge( 'cyan' );
 
 	/* #357. */
 	&.badge--observable {

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

@@ -32,6 +32,7 @@ $u-colors: (
 	'badge-red': #E50037,
 	'badge-black': #212121,
 	'badge-purple': #AB47BC,
+	'badge-cyan': hsl(189, 100%, 31%),
 
 	// Hints
 	'hint-info': #64B5F6,

package/themes/umberto/src/umberto/js/_filtering.js

@@ -14,6 +14,7 @@ export function enableFiltering() {
 		protected: storagePrefix + 'protected',
 		private: storagePrefix + 'private',
 		deprecated: storagePrefix + 'deprecated',
+		experimental: storagePrefix + 'experimental',
 		tree: 'filtering:tree'
 	};