umberto 5.0.2 → 6.1.0

package/themes/umberto/layout/umberto/_api-docs/_mixin/_api-see-source.pug

@@ -0,0 +1,11 @@
+mixin seeSource( item )
+	//- Do not render "See source" button if the module or the parsed item (e.g. a function) has the `@skipsource` annotation
+	if ( projectLocals.seeSourceRepositoryUrl && item.file && !( data.skipSource || item.skipSource ) )
+		- const link = item.file.url || projectLocals.getLinkToSource( projectLocals.seeSourceRepositoryUrl, item.file );
+
+		if link
+			.see-source
+				a( href=link target='_blank' rel="noopener noreferrer" )
+					svg( viewBox='0 0 1024 1024' )
+						path( d='M512 0C229.12 0 0 229.12 0 512c0 226.56 146.56 417.92 350.08 485.76 25.6 4.48 35.2-10.88 35.2-24.32 0-12.16-.64-52.48-.64-95.36-128.64 23.68-161.92-31.36-172.16-60.16-5.76-14.72-30.72-60.16-52.48-72.32-17.92-9.6-43.52-33.28-.64-33.92 40.32-.64 69.12 37.12 78.72 52.48 46.08 77.44 119.68 55.68 149.12 42.24 4.48-33.28 17.92-55.68 32.64-68.48-113.92-12.8-232.96-56.96-232.96-252.8 0-55.68 19.84-101.76 52.48-137.6-5.12-12.8-23.04-65.28 5.12-135.68 0 0 42.88-13.44 140.8 52.48 40.96-11.52 84.48-17.28 128-17.28 43.52 0 87.04 5.76 128 17.28 97.92-66.56 140.8-52.48 140.8-52.48 28.16 70.4 10.24 122.88 5.12 135.68 32.64 35.84 52.48 81.28 52.48 137.6 0 196.48-119.68 240-233.6 252.8 18.56 16 34.56 46.72 34.56 94.72 0 68.48-.64 123.52-.64 140.8 0 13.44 9.6 29.44 35.2 24.32C877.44 929.92 1024 737.92 1024 512 1024 229.12 794.88 0 512 0z' )
+					| See source

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

@@ -0,0 +1,17 @@
+include _type
+
+mixin apiTitle( config )
+    div.api-header
+        img( src=relative_url( page.path, config.iconPath ) alt=config.kind title=config.kind )
+
+        div.api-header__title
+            h1( data-ln = data.longname )
+                != data.name
+
+                if ( config.kind !== 'Module' && page.shortHiddenPath )
+                    span.header__import--hidden
+                        != ` (${ page.shortHiddenPath })`
+
+            if ( page.realImportPath )
+                p.header__import
+                    != page.realImportPath

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

@@ -0,0 +1,30 @@
+mixin treeItem( node )
+    - const children = node.getChildren();
+    - const hasChildren = children && children.length > 0;
+    - let dataAttr = {};
+
+    - if ( node.getProp( 'access' ) ) dataAttr[ `data-${node.getProp('access')}` ] = 'true';
+
+    li( class= hasChildren ? "toggler--collapsed" : "" )&attributes(dataAttr)
+        - let wrapperClass = "tree__item__wrapper";
+
+        - const classStr = "tree__item--"  + node.getProp( 'type' ) + " tree__item__text";
+        - const link = node.getUrl();
+        - const longname = node.getProp( 'longname' );
+
+        if !hasChildren
+            a( href=link )
+                div( class = wrapperClass data-ln = longname )
+                    span( class = classStr )
+                        | #{ node.getProp( 'name' ) }
+        else
+            div( class = wrapperClass data-ln = longname )
+                if ( link )
+                    a( class = classStr href=link )
+                        | #{ node.getProp( 'name' ) }
+                else
+                    span( class = classStr )
+                        | #{ node.getProp( 'name' ) }
+            ul
+                each child in children
+                    +treeItem( child )

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

@@ -0,0 +1,17 @@
+mixin badge( bdg )
+    = "\n"
+
+    - const classStr = `badge badge--${bdg.class} ${bdg.info ? "badge--has-invert" : ""}`;
+
+    if bdg.linkTo
+            span( class = classStr )
+                a( href= bdg.linkTo ) #{ bdg.text }
+                    if bdg.info
+                        | !{' '}
+                        span.badge__invert #{ bdg.info }
+
+    else
+        span( class = classStr ) #{ bdg.text }
+            if bdg.info
+                | !{' '}
+                span.badge__invert #{ bdg.info }

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

@@ -0,0 +1,29 @@
+include ./_link-or-text.pug
+include ./_badge.pug
+include ./_dev-names.pug
+include ./_api-see-source.pug
+
+//- todo: actually these shouldnt be collapsing-list__items
+mixin classItem( item )
+	- const attrData = createFilterAttribs( item );
+
+	li( class="collapsing-list__item collapsing-list__item--visible" )&attributes( attrData )
+		div( class="collapsing-list__term" id=item.id )
+			h3
+				if isNonEmptyArray( item.badges )
+					p.badges
+						each badge in item.badges
+							+badge( badge )
+
+				code
+					+linkOrText( item.longname, {
+						linkText: item.name
+					} )
+
+				+devNames( item.longname )
+
+		if ( item.description && item.description.excerpt )
+			div.collapsing-list__description
+				p( class="collapsing-list__excerpt collapsing-list__excerpt--short" )
+					| !{ item.description.excerpt }
+				+seeSource( item )

package/themes/umberto/layout/umberto/_api-docs/_mixin/_dev-names.pug

@@ -0,0 +1,9 @@
+//- Generates a full name of a member that allows creating a link from any module.
+//-
+//- @param {String} name The `doclet#longname` property.
+//- @param {String|undefined} label A description of an overloaded member.
+mixin devNames( name, label )
+	- const nameToDisplay = label ? `${ name }:${ label }` : name;
+
+	span.collapsing-list__dev-names( aria-hidden='true', title=nameToDisplay )
+		code #{ nameToDisplay }

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

@@ -0,0 +1,23 @@
+include _params
+include _type
+include _link-or-text
+
+mixin error( err )
+	li( class="collapsing-list__item collapsing-list__item--visible" )
+		div( class="collapsing-list__term toggler--collapsed" id=err.id )
+			h3
+				code
+					a( class="member-name" href="#" + err.id ) #{ err.name }
+
+		div.collapsing-list__description.collapsing-list__description--error-page
+			if ( err.description && err.description.excerpt )
+				p.collapsing-list__excerpt
+					| !{ err.description.excerpt }
+
+			div.collapsing-list__content
+				if ( err.description )
+					| !{ err.description.content }
+
+				if isNonEmptyArray( err.params )
+					h4 Parameters
+					+paramsMixin( err.params )

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

@@ -0,0 +1,7 @@
+include _link-or-text
+
+mixin firesItem( longname )
+    - const { label } = splitLongname( longname );
+
+    li
+        +linkOrText( longname, { linkText: label } )

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

@@ -0,0 +1,14 @@
+include ./_link-or-text.pug
+
+mixin hierarchy-item( items )
+    - const item = items.shift();
+    - const tooltip = getApiInfoboxTooltip( item, getRealImportPath );
+
+    li( title=tooltip )
+        code
+            +linkOrText( item )
+
+
+        if ( items.length > 0 )
+            ul
+                +hierarchy-item( items )

package/themes/umberto/layout/umberto/_api-docs/_mixin/_hierarchy-list.pug

@@ -0,0 +1,7 @@
+include ./_hierarchy-item.pug
+
+mixin hierarchyList( items )
+    dt Hierarchy
+    dd
+        ul.hierarchy-list
+            +hierarchy-item( items )

package/themes/umberto/layout/umberto/_api-docs/_mixin/_link-or-text.pug

@@ -0,0 +1,43 @@
+//- @param {String} name
+//- @param {Object} [options]
+//- @param {String} [options.aClass]
+//- @param {String} [options.linkText]
+mixin linkOrText( name, options = {} )
+	- const extracted = extractLongname( name );
+
+	span #{ extracted.prefix }
+		each longname, index in extracted.longnames
+			- const { aClass, linkText } = options;
+			- const parts = splitLongname( longname );
+			- const linkLongname = getUrlAddressFromLongname( parts );
+			- const hashSplit = longname.split( '#' );
+
+			- const linkHashSplit = linkLongname ? linkLongname.split( '#' ) : hashSplit;
+			- const linkAutoHash = linkHashSplit.length > 1 ? linkHashSplit[ 1 ] : '';
+			- const link = longnameToUrl( linkHashSplit[ 0 ], linkAutoHash );
+
+			- let nameText = '';
+
+			if ( linkText )
+				- nameText = linkText;
+			else
+				if ( parts.className )
+					- nameText = parts.className
+					if ( parts.className !== parts.name )
+						- nameText += ( parts.isStatic ? '.' : '#' ) + parts.name
+				else
+					- nameText = parts.name || parts.longnameBase
+				if ( parts.name === 'event' && parts.label )
+					- nameText += `:${ parts.label }`
+
+			- nameText = htmlsafe( nameText );
+
+			if ( link )
+				a( class=aClass href=link.replace( 'event:', 'event-') ) !{ nameText }
+			else
+				| #{ nameText }
+
+			if index < extracted.longnames.length - 1
+				| #{ extracted.separators[ index ] }
+
+		| #{ extracted.suffix }

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

@@ -0,0 +1,89 @@
+include _badge
+include _type
+include _params
+include _return
+include _fires-item
+include _link-or-text
+include ./_api-see-source.pug
+include ./_dev-names.pug
+include ./_related.pug
+include ./type-parameter
+
+mixin method( met )
+	- let attrData = createFilterAttribs( met );
+	- const itemClasses = [ 'collapsing-list__item', 'collapsing-list__item--visible' ];
+
+	li( class = itemClasses )&attributes( attrData )
+		- const id = encodeURI( met.id )
+		div( class="collapsing-list__term toggler--collapsed" id=id )
+			h3
+				//- badges
+				if isNonEmptyArray( met.badges )
+					p.badges
+						each badge in met.badges
+							+badge( badge )
+
+				code
+					a( class="member-name" href="#" + id ) #{ met.name }
+
+					//- params ( param1, [param2] )
+					| (
+					if isNonEmptyArray( met.params )
+						each param, index in met.params
+							if param.optional
+								|  [ #{ param.name } ]
+							else
+								|  #{ param.name }
+							if ( 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
+								| !{ ' ' }
+					| )
+
+					//- returns
+					if isNonEmptyArray( met.returns )
+						|  &rarr; !{' '}
+						if isNonEmptyArray( met.returns[0].types )
+							+type( met.returns[0].types )
+
+
+				+devNames( met.longname, met.label )
+
+		div.collapsing-list__description
+			if ( met.description && met.description.excerpt )
+				div.collapsing-list__excerpt
+					p !{ met.description.excerpt }
+
+			div.collapsing-list__content
+				+seeSource( met )
+
+				if ( met.description )
+					| !{ met.description.content }
+
+				if isNonEmptyArray( met.typeParameters )
+					h4 Type parameters
+					dl
+						each type in met.typeParameters
+							+typeParameter( type )
+
+				if isNonEmptyArray( met.params )
+					h4 Parameters
+					+paramsMixin( met.params )
+
+				if isNonEmptyArray( met.returns )
+					h4 Returns
+					dl
+						each ret in met.returns
+							+return( ret )
+
+				if isNonEmptyArray( met.fires )
+					h4 Fires
+					ul
+						each longname in met.fires
+							+firesItem( longname )
+
+				if isNonEmptyArray( met.see )
+					+related( met.see )

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

@@ -0,0 +1,44 @@
+mixin paramsMixin ( params, level, title )
+    - const baseLevel = 4;
+    - const hLevel = level || 4;
+    - const heading = 'h' + hLevel;
+    - const titleText = title || 'Parameters';
+
+    if ( hLevel > baseLevel )
+        div( class="dlheading" + hLevel )
+            != titleText
+
+    dl
+        each param in params
+            - const isComputedProperty = param.id === 'member-__index';
+
+            dt
+                code
+                    if isComputedProperty
+                        - const [ parentParam, nestedParam ] = param.name.split( '.' );
+
+                        | #{ parentParam }
+                        i
+                            | #{ nestedParam }
+                    else if param.optional
+                        | [ #{ param.name } ]
+                    else
+                        | #{ param.name }
+
+                    if isNonEmptyArray( param.types )
+                        | :
+                        | !{ ' ' }
+                        +type( param.types )
+
+            dd
+                if ( param.description )
+                    | !{ param.description.content }
+
+                if isNonEmptyArray( param.params )
+                    //- nested params
+                    +paramsMixin( param.params, hLevel+1, param.subParamsText || 'Properties' )
+
+                if param.defaultvalue
+                    p Defaults to
+                        | !{ ' ' }
+                        code #{ param.defaultvalue }

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

@@ -0,0 +1,51 @@
+include _params
+include ./_type.pug
+include ./_badge.pug
+include ./_dev-names.pug
+include ./_api-see-source.pug
+include ./_related.pug
+
+mixin property( prop )
+	- const attrData = createFilterAttribs( prop );
+	- const itemClasses = [ 'collapsing-list__item', 'collapsing-list__item--visible' ];
+
+	li( class = itemClasses )&attributes( attrData )
+		div( class="collapsing-list__term toggler--collapsed" id=prop.id )
+			h3
+				if isNonEmptyArray( prop.badges )
+					p.badges
+						each badge in prop.badges
+							+badge( badge )
+
+				code
+					a( class="member-name" href="#" + prop.id ) #{ prop.name }
+
+					if isNonEmptyArray( prop.types )
+						|  :!{' '}
+						+type( prop.types, prop.optional )
+
+				+devNames( prop.longname )
+
+		div.collapsing-list__description
+			if ( prop.description && prop.description.excerpt )
+				div.collapsing-list__excerpt
+					p !{ prop.description.excerpt }
+
+			div.collapsing-list__content
+				+seeSource( prop )
+
+				if ( prop.description )
+					| !{ prop.description.content }
+
+				if prop.defaultvalue
+					p Defaults to
+						| !{ ' ' }
+						code #{ prop.defaultvalue }
+
+				if isNonEmptyArray( prop.params )
+					h4 Parameters
+					+paramsMixin( prop.params )
+
+				if isNonEmptyArray( prop.see )
+					+related( prop.see )
+

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

@@ -0,0 +1,8 @@
+include ./_link-or-text.pug
+
+mixin related( seeArr )
+	h4 Related:
+	ul
+		each seeItem in seeArr
+			li
+				+linkOrText( seeItem )

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

@@ -0,0 +1,14 @@
+include ./_type.pug
+include ./_params.pug
+
+mixin return( ret )
+    dt
+        code
+            if ret.types
+                +type( ret.types )
+    dd
+        if ( ret.description )
+            | !{ ret.description.content }
+
+        if isNonEmptyArray( ret.params )
+            +paramsMixin( ret.params, 5, 'Properties' )

package/themes/umberto/layout/umberto/_api-docs/_mixin/_sidebox-list-item.pug

@@ -0,0 +1,8 @@
+include ./_link-or-text.pug
+
+mixin sideboxListItem( data )
+    - const tooltip = getApiInfoboxTooltip( data, getRealImportPath );
+
+    li( title=tooltip)
+        code
+            +linkOrText( data )

package/themes/umberto/layout/umberto/_api-docs/_mixin/_sidebox-list.pug

@@ -0,0 +1,8 @@
+include ./_sidebox-list-item.pug
+
+mixin sideboxList( items, title )
+    dt #{ title }
+    dd
+        ul
+            each item in items
+                +sideboxListItem( item )

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

@@ -0,0 +1,180 @@
+include ./_link-or-text.pug
+
+mixin type( types, isOptional = false )
+	each nameOrObject, index in types
+		+renderType( nameOrObject )
+
+		if index < types.length - 1
+			| !{ ' | ' }
+
+	if ( isOptional && !types.includes( 'undefined' ) )
+		| !{ ' | ' }
+		+renderType( 'undefined' )
+
+//- TODO: Description.
+//-
+//- @param {String|*} inlineObjectOrType
+mixin renderStringValue( inlineObjectOrType )
+	//- An inline object specified as string.
+	if ( typeof inlineObjectOrType === 'string' && inlineObjectOrType.startsWith( '{' ) )
+		| !{ inlineObjectOrType }
+	else
+		+linkOrText( inlineObjectOrType, {
+			aClass: 'collapsing-list__type'
+		} )
+
+//- TODO: Description.
+//-
+//- @param {Object} complexType
+//- @param {'function'|'predicate'|'operator'|'generic'} complexType.type
+//- @param {Array.<*>} [complexType.params]
+//- @param {String} [complexType.name]
+//- @param {Array.<*>} [complexType.instances]
+//- @param {String} [complexType.operator]
+//- @param {Array.<*>} [complexType.values]
+//- @param {String} [complexType.name]
+//- @param {Array.<*>} [complexType.typeParameters]
+mixin renderComplexStructure( complexType )
+	//- Inline callback.
+	if ( complexType.type === 'function' && complexType.params && complexType.returns )
+		+renderInlineFunction( complexType )
+
+	//- Predicate.
+	//-
+	//- The goal is to display whether an object is an instance of an array of modules.
+	//- E.g.: `this is "Model"`
+	if ( complexType.type === 'predicate' && complexType.name && complexType.instances )
+		i= complexType.name
+		| !{ ' is ' }
+		+renderUnion( complexType.instances )
+
+	//- Type operator.
+	//-
+	//- The goal is to display the type operator keyword before rendering a type.
+	if ( complexType.type === 'operator' && complexType.operator && complexType.values )
+		i= complexType.operator
+		| !{ ' ' }
+		+renderType( complexType.values )
+
+	//- An object with type arguments.
+	if ( complexType.type === 'generic' && complexType.name && ( complexType.typeParameters || complexType.typeParameter ) )
+		+renderGenericType( complexType )
+
+
+//- Renders a structure for an union, an array or a single type specified as a string.
+//-
+//-	* Union: Foo | Bar | Baz
+//-	* Array: Array<Foo | Bar | Baz>
+//-	* String: Foo
+//-
+//- All types are linkable if they point to an existing JSDoc doclet.
+//-
+//- @param {Set|Array|String} type
+mixin renderType( type )
+	//- Because of `typeof null === 'object'`...
+	if ( type )
+		//- Backward compatibility, when passing a `module:...` string.
+		if ( typeof type === 'string' )
+			+renderStringValue( type )
+		//- `intrinsic` type.
+		else if ( type.elementType )
+			| #{ type.elementType.name }
+		else
+			//- Complex structures introduced when generating API pages from TypeScript.
+			if ( type instanceof Set )
+				+renderUnion( [ ...type ] )
+			else if ( Array.isArray( type ) )
+				| !{ 'Array&lt;' }
+				+renderUnion( type )
+				| !{ '&gt;' }
+			else if ( typeof type === 'object' )
+				+renderComplexStructure( type )
+
+//- Renders an union structure, e.g., `Foo | Bar | Baz`.
+//-
+//- All types are linkable if they point to an existing JSDoc doclet.
+//-
+//- @param {Array.<String>} type
+mixin renderUnion( iterable )
+	each item, index in iterable
+		+renderType( item )
+		if index < iterable.length - 1
+			| !{ ' | ' }
+
+//- Draws an inline callback structure.
+//-
+//- E.g.: `( ArgumentFoo | ArgumentBar, AnotherArgument ) => ReturnType`
+//- If specified names are modules, they should point to the proper API page.
+//-
+//- @param {Object} callback
+//- @param {String} callback.type
+//- @param {Array} callback.params
+//- @param {Object} callback.returns
+//- @param {Boolean} callback.isClass
+mixin renderInlineFunction( callback )
+	if ( callback.isClass )
+		i !{ 'new' }
+		| !{ ' ' }
+
+	//- (1) Start with an opening parenthesis.
+	//- It prints `( ` or `(` depending on required arguments by a callback.
+	if ( callback.params.length )
+		| (!{ ' ' }
+	else
+		| (
+
+	//- (2) Arguments parsing. They are seperated by coma (`, `).
+	each paramObject, paramIndex in callback.params
+		//- (3) Process a single argument.
+		+renderType( paramObject )
+		if paramIndex < callback.params.length - 1
+			| !{ ', ' }
+
+	//- (4) Close the parenthesis. Define the returned type.
+	//- It prints ` ) => ` or `) => ` depending on required arguments by the callback.
+	if ( callback.params.length )
+		| !{ ' ' }) =&gt; !{ ' ' }
+	else
+		| ) =&gt; !{ ' ' }
+
+	//- Wraps the returned type in brackets to avoid confusions if a type is returned by the callback,
+	//- or it is a new type (outside the callback). See #1063.
+	if ( callback.returns instanceof Set )
+		| (!{ ' ' }
+
+	//- (5) Process the returned type that can be an union, an array of a type.
+	+renderType( callback.returns )
+
+	//- See #1063.
+	if ( callback.returns instanceof Set )
+		| !{ ' ' })
+
+//- TODO: Description
+//-
+//- @param {Object} generic
+//- @param {'generic'} generic.type
+//- @param {String} generic.name
+//- @param {Set.<String>} generic.names
+//- @param {Array.<*>} [generic.typeParameters]
+//- @param {*} [generic.typeParameter]
+mixin renderGenericType( generic )
+	+renderType( generic.name )
+
+	if ( generic.typeParameters )
+		| !{ '&lt;' }
+		each type, typeIndex in generic.typeParameters
+			if ( typeof type === 'string' )
+				+renderStringValue( type )
+			else
+				//- Nested generics.
+				+renderGenericType( type )
+
+			if typeIndex < generic.typeParameters.length - 1
+				| !{ ', ' }
+		| !{ '&gt;' }
+
+	if ( generic.typeParameter )
+		| !{ '&lsqb; ' }
+		+renderType( generic.typeParameter )
+		| !{ ' &rsqb;' }
+

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

@@ -0,0 +1,18 @@
+include ./_type
+
+mixin typeParameter( type )
+	dt
+		code
+			span !{ type.name }
+
+			//- 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 )
+
+	if ( type.description )
+		dd
+			| !{ type.description.content }