feat(dgeni,daffio): render API package descriptions (#3031)

--------- Co-authored-by: xelaint <xelaint@gmail.com>
graycoreio · Aug 26, 2024 · 76cb889 · 76cb889
1 parent 3e1fe98
commit 76cb889
Show file tree

Hide file tree

Showing 9 changed files with 38 additions and 11 deletions.
diff --git a/apps/daffio/src/app/docs/api/components/api-list-section/api-list-section-theme.scss b/apps/daffio/src/app/docs/api/components/api-list-section/api-list-section-theme.scss
@@ -7,13 +7,22 @@
 
 	.daffio-api-list-section {
 		&__item {
+			color: $base-contrast;
+
 			&:focus {
 				box-shadow: 0 0 0 4px rgba($base-contrast, 0.1);
 				outline: none;
 			}
 
-			&:after {
+			&::after {
 				background: daff-theme.daff-illuminate($base, $neutral, 2);
+				opacity: 0;
+			}
+
+			&:hover {
+				&::after {
+					opacity: 1;
+				}
 			}
 		}
 	}

diff --git a/apps/daffio/src/app/docs/api/components/api-list-section/api-list-section.component.scss b/apps/daffio/src/app/docs/api/components/api-list-section/api-list-section.component.scss
@@ -25,6 +25,7 @@ $api-list-section-item-border-radius: 4px;
 	&__item {
 		display: flex;
 		align-items: center;
+		gap: 16px;
 		border-radius: $api-list-section-item-border-radius;
 		font-weight: normal;
 		justify-content: space-between;
@@ -40,15 +41,12 @@ $api-list-section-item-border-radius: 4px;
 			top: 0;
 			height: 100%;
 			width: 100%;
-			opacity: 0;
 			transition: opacity 300ms;
 			z-index: 1;
 		}
 
 		&:hover {
-			&::after {
-				opacity: 1;
-			}
+			text-decoration: none;
 		}
 	}
 
@@ -58,9 +56,8 @@ $api-list-section-item-border-radius: 4px;
 
 	&__item-label {
 		@include type-mixin.type-label();
-		height: 1.5rem;
+		flex: 0 0 auto;
 		padding: 4px;
-		margin-left: 16px;
 	}
 
 	&__item-name,

diff --git a/apps/daffio/src/app/docs/api/components/api-list-section/api-list-section.component.ts b/apps/daffio/src/app/docs/api/components/api-list-section/api-list-section.component.ts
@@ -6,12 +6,17 @@ import {
 } from '@angular/core';
 import { RouterLink } from '@angular/router';
 
+import { DaffArticleEncapsulatedDirective } from '@daffodil/design';
+
 import { DaffioApiReference } from '../../models/api-reference';
 
 @Component({
   selector: 'daffio-api-list-section',
   templateUrl: './api-list-section.component.html',
   styleUrls: ['./api-list-section.component.scss'],
+  hostDirectives: [{
+    directive: DaffArticleEncapsulatedDirective,
+  }],
   changeDetection: ChangeDetectionStrategy.OnPush,
   standalone: true,
   imports: [

diff --git a/apps/daffio/src/app/docs/api/models/api-doc.ts b/apps/daffio/src/app/docs/api/models/api-doc.ts
@@ -4,6 +4,7 @@ import { DaffioDoc } from '../../models/doc';
  * An object for an API document.
  */
 export interface DaffioApiDoc extends DaffioDoc {
+  description: string;
   docType: string;
   docTypeShorthand: string;
 }
diff --git a/apps/daffio/src/app/docs/components/doc-viewer/doc-viewer.component.html b/apps/daffio/src/app/docs/components/doc-viewer/doc-viewer.component.html
@@ -4,10 +4,11 @@
 </button>
 <div class="daffio-doc-viewer__grid">
   @if (isApiPackage) {
-    <div class="daffio-doc-viewer__content">
-      <h1 class="daffio-doc-viewer__title">{{doc.title}}</h1>
-	    <daffio-api-list-section [children]="doc.children"></daffio-api-list-section>
-    </div>
+    <daff-article class="daffio-doc-viewer__content">
+      <h1>{{doc.title}}</h1>
+      <p>{{doc.description}}</p>
+	    <daffio-api-list-section [children]="doc.children" class="daffio-doc-viewer__api-section"></daffio-api-list-section>
+    </daff-article>
   } @else {
     <daff-article
       class="daffio-doc-viewer__content"

diff --git a/apps/daffio/src/app/docs/components/doc-viewer/doc-viewer.component.scss b/apps/daffio/src/app/docs/components/doc-viewer/doc-viewer.component.scss
@@ -62,4 +62,8 @@
 			display: none;
 		}
 	}
+
+	&__api-section {
+		margin: 48px 0 0;
+	}
 }
diff --git a/apps/daffio/src/scss/type-descriptors/_mixins.scss b/apps/daffio/src/scss/type-descriptors/_mixins.scss
@@ -17,6 +17,7 @@ $base-contrast: daff-theme.daff-map-deep-get(daff-theme.$theme, 'core.base-contr
 	border-radius: 4px;
 	font-family: daff.$monospace-font-family;
 	font-size: 0.625rem;
+	line-height: 0.875rem;
 	box-sizing: border-box;
 	text-transform: uppercase;
 

diff --git a/tools/dgeni/src/processors/packages.ts b/tools/dgeni/src/processors/packages.ts
@@ -2,6 +2,9 @@ import {
   Processor,
   Document,
 } from 'dgeni';
+import * as path from 'path';
+
+import { API_SOURCE_PATH } from '../transforms/config';
 
 export class PackagesProcessor implements Processor {
   name = 'packages';
@@ -17,6 +20,10 @@ export class PackagesProcessor implements Processor {
           .replace('/src', '')
           .replace(/^.*libs\//, '');
         doc.docType = 'package';
+        try {
+          const packageJson = require(path.resolve(API_SOURCE_PATH, doc.id, 'package.json'));
+          doc.description = packageJson.description;
+        } catch {}
         // The name is actually the full id
         doc.name = this.nameComputer(doc.id);
       }

diff --git a/tools/dgeni/src/transforms/daffodil-api-package/helpers/generateApiList.ts b/tools/dgeni/src/transforms/daffodil-api-package/helpers/generateApiList.ts
@@ -6,6 +6,7 @@ interface DaffDocsApiNavigationList {
   id: string;
   title: string;
   path: string;
+  description?: string;
   docType: string;
   docTypeShorthand: string;
   children: Array<DaffDocsApiNavigationList>;
@@ -47,6 +48,7 @@ export function getPackageInfo(packageDoc): DaffDocsApiNavigationList {
   return {
     ...getExportInfo(packageDoc),
     title: packageDoc.name,
+    description: packageDoc.description,
     docType: 'package',
     docTypeShorthand: 'pk',
     children: packageDoc.exports