API Summary Style Customization (#17)

benri · deiteris · web-flow · commit 83db8258dcaf · 2021-04-19T17:48:37.000-03:00
* Refactor styles, add variable to adjust heading color (#14) * refactor: use variables for font-weights * feat: use existing variables to style endpoints title * feat: add variable to adjust section heading color * docs: adjust readme formatting * add css parts * part: separator, toc, api-title-label * hide toc * update unit tests * margin var * update type def * update doc * bump version Co-authored-by: Yury <RIP95_95@mail.ru>
diff --git a/README.md b/README.md
@@ -43,6 +43,35 @@ npm install --save @api-components/api-summary
 </html>
 ```
 
+### Styling using CSS Shadow Parts
+
+```html
+<html>
+  <head>
+    <script type="module">
+      import '@api-components/api-summary/api-summary.js';
+    </script>
+    <style type="text/css">
+      api-summary::part(api-title) {
+        font-size: 24px;
+      }
+    </style>
+  </head>
+  <body>
+    <api-summary exportparts="api-title"></api-summary>
+    <script>
+    const amf = await getAmfModel();
+    document.body.querySelector('api-summary').api = amf;
+    window.addEventListener('api-navigation-selection-changed', (e) => {
+      console.log(e.detail.selected);
+      console.log(e.detail.type);
+    });
+    </script>
+  </body>
+</html>
+```
+For a complete list of parts, check out this [doc](./Styling.md).
+
 ### In a LitElement template
 
 ```js
diff --git a/Styling.md b/Styling.md
@@ -0,0 +1,13 @@
+# Styling
+
+## List of CSS Shadow Parts
+ 
+- `api-title`
+- `api-title-label`
+- `api-version`
+- `marked-description`
+- `info-section`
+- `info-inline-desc`
+- `license-section`
+- `separator`
+- `toc`
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@api-components/api-summary",
   "description": "A summary view for an API base on AMF data model",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "license": "Apache-2.0",
   "main": "index.js",
   "module": "index.js",
diff --git a/src/ApiSummary.d.ts b/src/ApiSummary.d.ts
@@ -24,6 +24,10 @@ export declare class ApiSummary extends AmfHelperMixin(LitElement) {
    * @attribute
    */
   titleLevel: string;
+  /**
+   * A property to hide the table of contents list of endpoints.
+   */
+  hideToc: boolean;
 
   _providerName: string;
   _providerEmail: string;
diff --git a/src/ApiSummary.js b/src/ApiSummary.js
@@ -43,6 +43,10 @@ export class ApiSummary extends AmfHelperMixin(LitElement) {
        * @default 2
        */
       titleLevel: { type: String },
+      /**
+       * A property to hide the table of contents list of endpoints.
+       */
+      hideToc: { type: Boolean },
 
       _providerName: { type: String },
       _providerEmail: { type: String },
@@ -99,6 +103,7 @@ export class ApiSummary extends AmfHelperMixin(LitElement) {
      * @type {string[]}
      */
     this.protocols = undefined;
+    this.hideToc = false;
   }
 
   __amfChanged() {
@@ -321,7 +326,7 @@ export class ApiSummary extends AmfHelperMixin(LitElement) {
         ${this._termsOfServiceTemplate()}
       </div>
 
-      ${this._endpointsTemplate()}
+      ${this.hideToc ? '' : this._endpointsTemplate()}
     `;
   }
 
@@ -331,8 +336,8 @@ export class ApiSummary extends AmfHelperMixin(LitElement) {
       return '';
     }
     return html`
-    <div class="api-title" role="heading" aria-level="${titleLevel}">
-    <label>API title:</label>
+    <div class="api-title" role="heading" aria-level="${titleLevel}" part="api-title">
+    <label part="api-title-label">API title:</label>
     <span>${_apiTitle}</span>
     </div>`;
   }
@@ -343,7 +348,7 @@ export class ApiSummary extends AmfHelperMixin(LitElement) {
       return '';
     }
     return html`
-    <p class="inline-description version">
+    <p class="inline-description version" part="api-version">
       <label>Version:</label>
       <span>${_version}</span>
     </p>`;
@@ -355,7 +360,7 @@ export class ApiSummary extends AmfHelperMixin(LitElement) {
       return '';
     }
     return html`
-    <div role="region" class="marked-description">
+    <div role="region" class="marked-description" part="marked-description">
       <arc-marked .markdown="${_description}" sanitize>
         <div slot="markdown-html" class="markdown-body"></div>
       </arc-marked>
@@ -427,16 +432,16 @@ export class ApiSummary extends AmfHelperMixin(LitElement) {
       `<a href="${_providerUrl}" target="_blank" class="app-link provider-url">${_providerUrl}</a>`,
     ): undefined;
     return html`
-    <section role="contentinfo" class="docs-section">
+    <section role="contentinfo" class="docs-section" part="info-section">
       <label class="section">Contact information</label>
-      <p class="inline-description">
+      <p class="inline-description" part="info-inline-desc">
         <span class="provider-name">${_providerName}</span>
         ${_providerEmail ? html`<a
             class="app-link link-padding provider-email"
             href="mailto:${_providerEmail}">${_providerEmail}</a>` : ''}
       </p>
       ${_providerUrl ? html`
-        <p class="inline-description">
+        <p class="inline-description" part="info-inline-desc">
           ${unsafeHTML(link)}
         </p>` : ''}
     </section>`;
@@ -451,7 +456,7 @@ export class ApiSummary extends AmfHelperMixin(LitElement) {
       `<a href="${_licenseUrl}" target="_blank" class="app-link">${_licenseName}</a>`,
     );
     return html`
-    <section aria-labelledby="licenseLabel" class="docs-section">
+    <section aria-labelledby="licenseLabel" class="docs-section" part="license-section">
       <label class="section" id="licenseLabel">License</label>
       <p class="inline-description">
         ${unsafeHTML(link)}
@@ -481,8 +486,8 @@ export class ApiSummary extends AmfHelperMixin(LitElement) {
     const result = _endpoints.map((item) => this._endpointTemplate(item));
     const pathLabel = this._isAsyncAPI(this.amf) ? 'channels' : 'endpoints';
     return html`
-    <div class="separator"></div>
-    <div class="toc">
+    <div class="separator" part="separator"></div>
+    <div class="toc" part="toc">
       <label class="section endpoints-title">API ${pathLabel}</label>
       ${result}
     </div>
diff --git a/src/Styles.js b/src/Styles.js
@@ -103,7 +103,7 @@ a:hover {
 .separator {
   background-color: var(--api-summary-separator-color, rgba(0, 0, 0, 0.12));
   height: 1px;
-  margin: 40px 0;
+  margin: var(--api-summary-separator-margin, 40px 0);
 }
 
 .endpoint-item {
diff --git a/test/api-summary.test.js b/test/api-summary.test.js
@@ -44,8 +44,8 @@ describe('ApiSummary', () => {
 
         it('renders api title', () => {
           const node = element.shadowRoot.querySelector('[role="heading"]');
-          assert.dom.equal(node, `<div aria-level="2" class="api-title" role="heading">
-            <label>
+          assert.dom.equal(node, `<div aria-level="2" class="api-title" role="heading" part="api-title">
+            <label part="api-title-label">
               API title:
             </label>
             <span>
@@ -96,6 +96,11 @@ describe('ApiSummary', () => {
           const node = element.shadowRoot.querySelector('api-url');
           assert.equal(node.url, `https://{instance}.domain.com`);
         });
+
+        it('renders endpoints template', () => {
+          const node = element.shadowRoot.querySelector('.endpoints-title');
+          assert.dom.equal(node, `<label class="endpoints-title section">API endpoints</label>`);
+        });
       });
 
       describe('OAS properties', () => {
@@ -411,6 +416,24 @@ describe('ApiSummary', () => {
           assert.equal(element.shadowRoot.querySelector('.section.endpoints-title').textContent, 'API channels');
         });
       });
+
+      describe('hideToc', () => {
+        let element = /** @type ApiSummary */ (null);
+        let amf;
+        before(async () => {
+          amf = await AmfLoader.load(compact);
+        });
+        beforeEach(async () => {
+          element = await basicFixture();
+          element.setAttribute('hideToc', 'true');
+          await aTimeout(0);
+        });
+
+        it('does not render endpoints template', () => {
+          const node = element.shadowRoot.querySelector('.toc');
+          assert.isNull(node);
+        });
+      });
     });
   });
 

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@api-components/api-summary",`
`3`	`3`	`"description": "A summary view for an API base on AMF data model",`
`4`		`- "version": "4.5.0",`
	`4`	`+ "version": "4.6.0",`
`5`	`5`	`"license": "Apache-2.0",`
`6`	`6`	`"main": "index.js",`
`7`	`7`	`"module": "index.js",`
Original file line number	Diff line number	Diff line change
`@@ -103,7 +103,7 @@ a:hover {`
`103`	`103`	`.separator {`
`104`	`104`	`background-color: var(--api-summary-separator-color, rgba(0, 0, 0, 0.12));`
`105`	`105`	`height: 1px;`
`106`		`- margin: 40px 0;`
	`106`	`+ margin: var(--api-summary-separator-margin, 40px 0);`
`107`	`107`	`}`
`108`	`108`
`109`	`109`	`.endpoint-item {`