umberto 6.0.0 → 6.1.0

package/themes/umberto/layout/{_partial → gloria/_partial}/gh-contribute.pug

@@ -2,7 +2,7 @@ if page.issuesUrl || page.contributeUrl
     div.github-contrib
         if page.contributeUrl
             a( href=page.contributeUrl title="Contribute to this guide" )
-                img( src=relative_url( page.path, 'assets/' + umbertoVersion + '/img/edit.svg' ) alt="Contribute to this guide" )
+                img( src=relative_url( page.path, 'assets/' + umbertoVersion + '/gloria/img/edit.svg' ) alt="Contribute to this guide" )
         if page.issuesUrl
             a( href=page.issuesUrl title="Report an issue" )
-                img( src=relative_url( page.path, 'assets/' + umbertoVersion + '/img/exclamation-circle.svg' ) alt="Report an issue" )
+                img( src=relative_url( page.path, 'assets/' + umbertoVersion + '/gloria/img/exclamation-circle.svg' ) alt="Report an issue" )

package/themes/umberto/layout/{_partial → gloria/_partial}/head.pug

@@ -25,7 +25,7 @@ if ( mainOg || ( projectLocals && projectLocals.og ) || page[ 'og-description' ]
 		- const hostname = mainOg.hostname || ogConfig.hostname;
 		meta( property='og:image' content= hostname + pathJoin( '/docs', page.latestBasePath || '/', ogConfig.image ? ogConfig.image : mainOg.image) )
 	meta( property='og:type' content='website' )
-	if ( page.layout === 'index' )
+	if ( page.layout === 'gloria/index' )
 		meta( property='og:url' content= page.canonicalUrlBeginning + 'index.html' )
 	else
 		meta( property='og:url' content= page.canonicalUrlBeginning + page.path.replace( page.BASE_PATH, projectLocals.latestBasePath ) )
@@ -51,7 +51,7 @@ if page.BASE_PATH
 if ( docSearchConfig && docSearchConfig.isEnabled && !disableSearch && (!projectLocals || !projectLocals.disableSearch) )
 	link( rel = 'stylesheet', href = docSearchConfig.css )
 
-link( rel = 'stylesheet', href = relative_url( page.path, 'assets/' + umbertoVersion + '/css/styles.css' ), type='text/css' media='all' )
+link( rel = 'stylesheet', href = relative_url( page.path, 'assets/' + umbertoVersion + '/gloria/css/styles.css' ), type='text/css' media='all' )
 
 if projectLocals
 	each path in projectLocals.extraStylePaths

package/themes/umberto/layout/{_partial → gloria/_partial}/search-box.pug

@@ -3,4 +3,4 @@ if !disableSearch && (!projectLocals || !projectLocals.disableSearch)
 	div.top__search
 		input( type="text", id="docsearch_input", class="top__search__box", placeholder=placeholder )
 		div( class="top__search__button")
-			img( src=relative_url( page.path, 'assets/' + umbertoVersion + '/img/loupe.svg' ) alt="Search" )
+			img( src=relative_url( page.path, 'assets/' + umbertoVersion + '/gloria/img/loupe.svg' ) alt="Search" )

package/themes/umberto/layout/{api.pug → gloria/api.pug}

@@ -4,7 +4,7 @@ block content
 	- const split = uSplitToTitleAndContent( page.content );
 
 	h1.main__content-title( data-ln = page.shortName === 'index' ? page[ 'default-expanded' ] || page.shortName : page.shortName )
-		img( src=relative_url( page.path, 'assets/' + umbertoVersion + '/img/cog.svg' ) alt="API" )
+		img( src=relative_url( page.path, 'assets/' + umbertoVersion + '/gloria/img/cog.svg' ) alt="API" )
 		!= split.title || page.title
 
 	!= split.content

package/themes/umberto/layout/{base.pug → gloria/base.pug}

@@ -32,7 +32,7 @@ html( lang='en' )
 		include _partial/footer
 		include _partial/docsearch
 
-		script( src = relative_url( page.path, pathJoin( 'assets', umbertoVersion, 'scripts/app.js' ) ) )
+		script( src = relative_url( page.path, pathJoin( 'assets', umbertoVersion, 'gloria/scripts/app.js' ) ) )
 
 		if page.isSnippetPage
 			//UMBERTO: SNIPPET: JS

package/themes/umberto/layout/{sdk.pug → gloria/sdk.pug}

@@ -4,7 +4,7 @@ block content
 	- const split = uSplitToTitleAndContent( page.content );
 
 	h1.main__content-title
-		img( src=relative_url( page.path, 'assets/' + umbertoVersion + '/img/book.svg' ) alt="guide" )
+		img( src=relative_url( page.path, 'assets/' + umbertoVersion + '/gloria/img/book.svg' ) alt="guide" )
 		!= split.title || page.title
 
 	if page.toc !== false

package/themes/umberto/layout/umberto/404.pug

@@ -0,0 +1,22 @@
+doctype html
+html( lang='en' )
+    head
+        meta( charset='utf-8' )
+        meta( name="viewport" content="width=device-width, initial-scale=1")
+        title= page[ 'meta-title' ] ? page[ 'meta-title' ] : page.title
+        link( rel = 'stylesheet', href = '/assets/' + umbertoVersion + '/umberto/css/styles.css', type='text/css' media='screen' )
+    body
+        header.top
+
+        main( class = 'main main--no-sitenav' )
+            section( class = 'main__content formatted' )
+
+                .main__content-inner
+                    - const split = uSplitToTitleAndContent( page.content );
+
+                    h1
+                        != split.title || page.title
+
+                    != split.content
+
+        include _partial/footer

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 )