feat: add CSS variables section in API Ref (#399)

lib/documentation/index.js

@@ -1,10 +1,12 @@
 const api = require('../../packages/main/dist/api.json');
+const cssVariables = require('../../packages/main/docs/themes/css-vars.json');
 const template = require('./templates/template').template;
 const sinceTemplate = require('./templates/api-component-since').template;
 const propertiesTemplate = require('./templates/api-properties-section').template;
 const slotsTemplate = require('./templates/api-slots-section').template;
 const eventsTemplate = require('./templates/api-events-section').template;
 const methodsTemplate = require('./templates/api-methods-section').template;
+const cssVariablesTemplate = require('./templates/api-css-variables-section').template;
 const Handlebars = require('handlebars/dist/handlebars.min.js');
 const fs = require('fs');
 const mkdirp = require('mkdirp');
@@ -18,7 +20,11 @@ const sinceMarker = "<!--since_tag_marker-->";
 const getComponentByName = name => {
 	return entries.find(element => {
 		return element.basename === name;
-	})
+	}) 
+};
+
+const getCSSVarsByName = name => {
+	return cssVariables[name] || [];
 };
 
 const capitalize = str => {
@@ -42,23 +48,34 @@ Handlebars.registerPartial('properties', propertiesTemplate);
 Handlebars.registerPartial('slots', slotsTemplate);
 Handlebars.registerPartial('events', eventsTemplate);
 Handlebars.registerPartial('methods', methodsTemplate);
+Handlebars.registerPartial('cssVariables', cssVariablesTemplate);
 
 mkdirp(`dist/test-resources/sap/ui/webcomponents/main/api`);
 
 let entriesAPI = [];
 
-const mergeParentAPI = entry => {
+const appendCSSVarsAPI = entry => {
+	entry.cssVariables = getCSSVarsByName(entry.basename);
+	return entry;
+}
+
+const calculateAPI = entry => {
 	if (entriesAPI.indexOf(entry.basename) !== -1) {
 		return entry;
 	}
 
 	let parent = getComponentByName(entry.extends) || {};
-	parent = { ...{ properties: [], events: [], slots: [] }, ...parent };
+
+	entry = appendCSSVarsAPI(entry);
+	parent = appendCSSVarsAPI(parent);
+
+	parent = { ...{ properties: [], events: [], slots: [], cssVariables: [] }, ...parent };
 
 	// extend component documentation
 	entry.properties = [...(entry.properties || []), ...(parent.properties || [])];
 	entry.events = [...(entry.events || []), ...(parent.events || [])];
 	entry.slots = [...(entry.slots || []), ...(parent.slots || [])];
+	entry.cssVariables = [...(entry.cssVariables || []), ...(parent.cssVariables || [])];
 
 	entriesAPI.push(entry.basename);
 
@@ -72,7 +89,7 @@ const appendAdditionalEntriesAPI = entry => {
 
 		additionalEntries.forEach(entryName => {
 			let additionalEntry = getComponentByName(entryName);
-			additionalEntry = mergeParentAPI(additionalEntry);
+			additionalEntry = calculateAPI(additionalEntry);
 			entry.additionalDocs.push(additionalEntry);
 		});
 	}
@@ -120,10 +137,10 @@ const generateSamplePage = entry => {
 }
 
 const generateComponentAPI = entry => {
-	// (1) merge parent API
-	entry = mergeParentAPI(entry);
+	// (1) calculate the API
+	entry = calculateAPI(entry);
 
-	// (2) append additional API for children
+	// (2) append additional API for composition components - List -> ListIems, TabContainer -> Tabs, Table -> TableRow/Column/Cell
 	entry = appendAdditionalEntriesAPI(entry);
 
 	// (3) generate sample page

lib/documentation/templates/api-css-variables-section.js

@@ -0,0 +1,24 @@
+module.exports = {
+    template: `
+      {{#if cssVariables}}
+        <h3 class="comment-api-title" >CSS variables</h3>
+        <p class="small-space-top">You can use the following CSS varialbes to change the component styling.</p>
+  
+        <div class="small-space-top api-table">
+          <div class="head api-table-header-roll">
+            <div class="cell api-table-header-cell">Name</div>
+            <div class="cell api-table-header-cell">Description</div>
+          </div>
+  
+          {{#each cssVariables}}
+            <div class="row {{checkEven @index}}">
+              <div class="cell api-table-content-cell api-table-content-cell-bold">{{this.name}}</div>
+              <div class="cell api-table-content-cell api-table-content-cell-description">
+                  {{{this.description}}}
+              </div>
+            </div>
+          {{/each}}
+  
+        </div>
+      {{/if}}`
+};

lib/documentation/templates/template.js

@@ -9,6 +9,7 @@ module.exports = {
             {{> slots this}}
             {{> events this}}
             {{> methods this}}
+            {{> cssVariables this}} 
           </section>
         </section>
       </div>
@@ -21,7 +22,8 @@ module.exports = {
           <section class="component-api space-top">
             {{> properties this}}
             {{> slots this}}
-            {{> events this}} 
+            {{> events this}}
+            {{> cssVariables this}} 
           </section>
         </section>
       </div>

packages/main/docs/themes/css-vars.json

@@ -0,0 +1,24 @@
+{
+	"GroupHeaderListItem": [
+		{
+			"name": "--ui5-group-header-listitem-background-color",
+			"description": "Defines the <code>ui5-li-groupheader</code> background color"
+		}
+	],
+	"ListItem": [
+		{
+			"name": "--ui5-listitem-background-color",
+			"description": "Defines the<code>ui5-li</code> background color"
+		}
+	],
+	"Panel": [
+		{
+			"name": "--ui5-panel-background-color",
+			"description": "Defines the <code>ui5-panel</code> background color"
+		},
+		{
+			"name": "--ui5-panel-bottom-border-color",
+			"description": "Defines the <code>ui5-panel</code> bottom border color"
+		}
+	]
+}

packages/main/src/themes/GroupHeaderListItem.css

@@ -1,7 +1,7 @@
 .sapMLIB.sapMGHLI {
 	height: 3rem;
 	color: var(--sapUiListTableGroupHeaderTextColor);
-	background: var(--_ui5_group_header_listitem_background_color);
+	background: var(--ui5-group-header-listitem-background-color);
 	padding-top: 1rem;
 	font-size: var(--sapMFontHeader6Size);
 	font-weight: var(--sapUiFontHeaderWeight);

packages/main/src/themes/ListItemBase.css

@@ -21,7 +21,7 @@ ui5-li .sap-phone .sapMLIB {
 	height: 3rem;
 	width: 100%;
 	padding: 0 1rem 0 1rem;
-	background: var(--_ui5_listitem_background_color);
+	background: var(--ui5-listitem-background-color);
 	box-sizing: border-box;
 }
 

packages/main/src/themes/Panel.css

@@ -12,7 +12,7 @@ ui5-panel {
 	overflow: hidden;
 	box-sizing: border-box;
 	position: relative;
-	background-color: var(--_ui5_panel_background_color);
+	background-color: var(--ui5-panel-background-color);
 }
 
 .sapMPanel > header {
@@ -77,7 +77,7 @@ ui5-panel {
 	box-sizing: border-box;
 	overflow: auto;
 	white-space: normal;
-	border-bottom: 1px solid var(--_ui5_panel_bottom_border_color);
+	border-bottom: 1px solid var(--ui5-panel-bottom-border-color);
 }
 
 .sapMPanelContent:focus {
@@ -87,7 +87,7 @@ ui5-panel {
 .sapMPanelWrappingDiv,
 .sapMPanelWrappingDivTb {
 	position: relative;
-	background-color: var(--_ui5_panel_background_color);
+	background-color: var(--ui5-panel-background-color);
 }
 
 .sapMPanelWrappingDiv {

packages/main/src/themes/base/GroupHeaderListItem-parameters.css

@@ -1,3 +1,3 @@
 :root {
-	--_ui5_group_header_listitem_background_color: var(--sapUiListGroupHeaderBackground);
+	--ui5-group-header-listitem-background-color: var(--sapUiListGroupHeaderBackground);
 }

packages/main/src/themes/base/ListItemBase-parameters.css

@@ -1,4 +1,4 @@
 :root {
+	--ui5-listitem-background-color: var(--sapUiListBackground);
 	--_ui5_listitembase_focus_width: 1px;
-	--_ui5_listitem_background_color: var(--sapUiListBackground);
 }

packages/main/src/themes/base/Panel-parameters.css

@@ -1,5 +1,5 @@
 :root {
+	--ui5-panel-background-color: var(--sapUiGroupContentBackground);
+	--ui5-panel-bottom-border-color: var(--sapUiGroupTitleBorderColor);
 	--_ui5_panel_focus_border: 1px dotted var(--sapUiContentFocusColor);
-	--_ui5_panel_background_color: var(--sapUiGroupContentBackground);
-	--_ui5_panel_bottom_border_color: var(--sapUiGroupTitleBorderColor);
 }