From 8cd3206477d74437a0e9baed9e0f7502629ba7f4 Mon Sep 17 00:00:00 2001
From: Karan Mistry <karan.mistry@siemens.com>
Date: Sat, 29 Mar 2025 10:59:04 +0530
Subject: [PATCH] fix(material-angular-io): streamline directive and component
 metadata handling in dgeni

Currently, docs is not grouped based on Components and Directives. This fix will separate those two sections.

Fixes #24093
---
 .../pages/component-viewer/component-api.scss |  1 +
 tools/dgeni/common/decorators.ts              | 16 ++++++----
 tools/dgeni/common/dgeni-definitions.ts       | 15 +++++-----
 tools/dgeni/common/directive-metadata.ts      |  2 +-
 tools/dgeni/common/sort-members.ts            | 10 ++-----
 tools/dgeni/processors/categorizer.ts         | 30 +++++++++++--------
 tools/dgeni/processors/entry-point-grouper.ts |  7 ++++-
 tools/dgeni/templates/class.template.html     | 17 ++++++++---
 .../dgeni/templates/entry-point.template.html |  9 ++++++
 tools/dgeni/templates/property.template.html  | 12 ++++----
 10 files changed, 74 insertions(+), 45 deletions(-)

diff --git a/material.angular.io/src/app/pages/component-viewer/component-api.scss b/material.angular.io/src/app/pages/component-viewer/component-api.scss
index d491b650aa41..bc44c524617d 100644
--- a/material.angular.io/src/app/pages/component-viewer/component-api.scss
+++ b/material.angular.io/src/app/pages/component-viewer/component-api.scss
@@ -31,6 +31,7 @@
 .docs-api-method-description-cell,
 .docs-api-property-description,
 .docs-api-class-export-label,
+.docs-api-component-selectors,
 .docs-api-directive-selectors,
 .docs-api-class-description,
 .docs-api-class-export-name {
diff --git a/tools/dgeni/common/decorators.ts b/tools/dgeni/common/decorators.ts
index 5a212003eeea..0b07a9be5f19 100644
--- a/tools/dgeni/common/decorators.ts
+++ b/tools/dgeni/common/decorators.ts
@@ -30,7 +30,11 @@ export function isProperty(doc: MemberDoc): boolean {
 }
 
 export function isDirective(doc: ClassExportDoc): boolean {
-  return hasClassDecorator(doc, 'Component') || hasClassDecorator(doc, 'Directive');
+  return hasClassDecorator(doc, 'Directive');
+}
+
+export function isComponent(doc: ClassExportDoc): boolean {
+  return hasClassDecorator(doc, 'Component');
 }
 
 export function isService(doc: ClassExportDoc): boolean {
@@ -50,12 +54,12 @@ export function isPrimaryExportDoc(doc: ApiDoc): boolean {
   return hasJsDocTag(doc, 'docs-primary-export');
 }
 
-export function getDirectiveSelectors(classDoc: CategorizedClassDoc): string[] | undefined {
-  if (classDoc.directiveMetadata) {
-    const directiveSelectors: string = classDoc.directiveMetadata.get('selector');
+export function getSelectors(classDoc: CategorizedClassDoc): string[] | undefined {
+  if (classDoc.metadata) {
+    const selectors: string = classDoc.metadata.get('selector');
 
-    if (directiveSelectors) {
-      return directiveSelectors
+    if (selectors) {
+      return selectors
         .replace(/[\r\n]/g, '')
         .split(/\s*,\s*/)
         .filter(s => s !== '');
diff --git a/tools/dgeni/common/dgeni-definitions.ts b/tools/dgeni/common/dgeni-definitions.ts
index 5b7865b61de4..0da3771dac50 100644
--- a/tools/dgeni/common/dgeni-definitions.ts
+++ b/tools/dgeni/common/dgeni-definitions.ts
@@ -29,12 +29,13 @@ export interface CategorizedClassLikeDoc extends ClassLikeExportDoc, Deprecation
 /** Extended Dgeni class document that includes extracted Angular metadata. */
 export interface CategorizedClassDoc extends ClassExportDoc, CategorizedClassLikeDoc {
   isDirective: boolean;
+  isComponent: boolean;
   isService: boolean;
   isNgModule: boolean;
   isTestHarness: boolean;
-  directiveExportAs?: string | null;
-  directiveSelectors?: string[];
-  directiveMetadata: Map<string, any> | null;
+  exportAs?: string | null;
+  selectors?: string[];
+  metadata: Map<string, any> | null;
   extendedDoc: ClassLikeExportDoc | undefined;
   inheritedDocs: ClassLikeExportDoc[];
 }
@@ -42,10 +43,10 @@ export interface CategorizedClassDoc extends ClassExportDoc, CategorizedClassLik
 /** Extended Dgeni property-member document that includes extracted Angular metadata. */
 export interface CategorizedPropertyMemberDoc extends PropertyMemberDoc, DeprecationInfo {
   description: string;
-  isDirectiveInput: boolean;
-  isDirectiveOutput: boolean;
-  directiveInputAlias: string;
-  directiveOutputAlias: string;
+  isInput: boolean;
+  isOutput: boolean;
+  inputAlias: string;
+  outputAlias: string;
 }
 
 /** Extended Dgeni method-member document that simplifies logic for the Dgeni template. */
diff --git a/tools/dgeni/common/directive-metadata.ts b/tools/dgeni/common/directive-metadata.ts
index 69eb3797297e..f4d3881ac297 100644
--- a/tools/dgeni/common/directive-metadata.ts
+++ b/tools/dgeni/common/directive-metadata.ts
@@ -16,7 +16,7 @@ import {CategorizedClassDoc} from './dgeni-definitions';
  * export class MyComponent {}
  * ```
  */
-export function getDirectiveMetadata(classDoc: CategorizedClassDoc): Map<string, any> | null {
+export function getMetadata(classDoc: CategorizedClassDoc): Map<string, any> | null {
   const declaration = classDoc.symbol.valueDeclaration;
   const decorators =
     declaration && ts.isClassDeclaration(declaration) ? ts.getDecorators(declaration) : null;
diff --git a/tools/dgeni/common/sort-members.ts b/tools/dgeni/common/sort-members.ts
index 656eda962783..f9acca5364c4 100644
--- a/tools/dgeni/common/sort-members.ts
+++ b/tools/dgeni/common/sort-members.ts
@@ -41,17 +41,11 @@ export function sortCategorizedPropertyMembers(
   }
 
   // Sort in the order of: Inputs, Outputs, neither
-  if (
-    (docA.isDirectiveInput && !docB.isDirectiveInput) ||
-    (docA.isDirectiveOutput && !docB.isDirectiveInput && !docB.isDirectiveOutput)
-  ) {
+  if ((docA.isInput && !docB.isInput) || (docA.isOutput && !docB.isInput && !docB.isOutput)) {
     return -1;
   }
 
-  if (
-    (docB.isDirectiveInput && !docA.isDirectiveInput) ||
-    (docB.isDirectiveOutput && !docA.isDirectiveInput && !docA.isDirectiveOutput)
-  ) {
+  if ((docB.isInput && !docA.isInput) || (docB.isOutput && !docA.isInput && !docA.isOutput)) {
     return 1;
   }
 
diff --git a/tools/dgeni/processors/categorizer.ts b/tools/dgeni/processors/categorizer.ts
index d462e6e178b6..32ec21a190cb 100644
--- a/tools/dgeni/processors/categorizer.ts
+++ b/tools/dgeni/processors/categorizer.ts
@@ -6,7 +6,8 @@ import {MemberDoc} from 'dgeni-packages/typescript/api-doc-types/MemberDoc';
 import {getInheritedDocsOfClass} from '../common/class-inheritance';
 import {
   decorateDeprecatedDoc,
-  getDirectiveSelectors,
+  getSelectors,
+  isComponent,
   isDirective,
   isMethod,
   isNgModule,
@@ -22,7 +23,7 @@ import {
   CategorizedPropertyMemberDoc,
   CategorizedTypeAliasExportDoc,
 } from '../common/dgeni-definitions';
-import {getDirectiveMetadata} from '../common/directive-metadata';
+import {getMetadata} from '../common/directive-metadata';
 import {normalizeFunctionParameters} from '../common/normalize-function-parameters';
 import {isPublicDoc} from '../common/private-docs';
 import {getInputBindingData, getOutputBindingData} from '../common/property-bindings';
@@ -41,7 +42,8 @@ export function categorizer(exportSymbolsToDocsMap: Map<ts.Symbol, ClassLikeExpo
  * Processor to add properties to docs objects.
  *
  * isMethod     | Whether the doc is for a method on a class.
- * isDirective  | Whether the doc is for a @Component or a @Directive
+ * isComponent  | Whether the doc is for a @Component
+ * isDirective  | Whether the doc is for a @Directive
  * isService    | Whether the doc is for an @Injectable
  * isNgModule   | Whether the doc is for an NgModule
  */
@@ -111,7 +113,7 @@ export class Categorizer implements Processor {
     // clauses for the Dgeni document. To make the template syntax simpler and more readable,
     // store the extended class in a variable.
     classDoc.extendedDoc = classDoc.extendsClauses[0] ? classDoc.extendsClauses[0].doc! : undefined;
-    classDoc.directiveMetadata = getDirectiveMetadata(classDoc);
+    classDoc.metadata = getMetadata(classDoc);
     classDoc.inheritedDocs = getInheritedDocsOfClass(classDoc, this._exportSymbolsToDocsMap);
 
     classDoc.methods.push(
@@ -134,10 +136,14 @@ export class Categorizer implements Processor {
     }
 
     // Categorize the current visited classDoc into its Angular type.
-    if (isDirective(classDoc) && classDoc.directiveMetadata) {
+    if (isComponent(classDoc) && classDoc.metadata) {
+      classDoc.isComponent = true;
+      classDoc.exportAs = classDoc.metadata.get('exportAs');
+      classDoc.selectors = getSelectors(classDoc);
+    } else if (isDirective(classDoc) && classDoc.metadata) {
       classDoc.isDirective = true;
-      classDoc.directiveExportAs = classDoc.directiveMetadata.get('exportAs');
-      classDoc.directiveSelectors = getDirectiveSelectors(classDoc);
+      classDoc.exportAs = classDoc.metadata.get('exportAs');
+      classDoc.selectors = getSelectors(classDoc);
     } else if (isService(classDoc)) {
       classDoc.isService = true;
     } else if (isNgModule(classDoc)) {
@@ -190,17 +196,17 @@ export class Categorizer implements Processor {
 
     const metadata =
       propertyDoc.containerDoc.docType === 'class'
-        ? (propertyDoc.containerDoc as CategorizedClassDoc).directiveMetadata
+        ? (propertyDoc.containerDoc as CategorizedClassDoc).metadata
         : null;
 
     const inputMetadata = metadata ? getInputBindingData(propertyDoc, metadata) : null;
     const outputMetadata = metadata ? getOutputBindingData(propertyDoc, metadata) : null;
 
-    propertyDoc.isDirectiveInput = !!inputMetadata;
-    propertyDoc.directiveInputAlias = (inputMetadata && inputMetadata.alias) || '';
+    propertyDoc.isInput = !!inputMetadata;
+    propertyDoc.inputAlias = (inputMetadata && inputMetadata.alias) || '';
 
-    propertyDoc.isDirectiveOutput = !!outputMetadata;
-    propertyDoc.directiveOutputAlias = (outputMetadata && outputMetadata.alias) || '';
+    propertyDoc.isOutput = !!outputMetadata;
+    propertyDoc.outputAlias = (outputMetadata && outputMetadata.alias) || '';
   }
 
   /**
diff --git a/tools/dgeni/processors/entry-point-grouper.ts b/tools/dgeni/processors/entry-point-grouper.ts
index 84c954c0c57d..59d49d1edcbc 100644
--- a/tools/dgeni/processors/entry-point-grouper.ts
+++ b/tools/dgeni/processors/entry-point-grouper.ts
@@ -47,6 +47,9 @@ export class EntryPointDoc {
   /** List of categorized class docs that are defining a directive. */
   directives: CategorizedClassDoc[] = [];
 
+  /** List of categorized class docs that are defining a component. */
+  components: CategorizedClassDoc[] = [];
+
   /** List of categorized class docs that are defining a service. */
   services: CategorizedClassDoc[] = [];
 
@@ -124,7 +127,9 @@ export class EntryPointGrouper implements Processor {
       entryPoint.packageDisplayName = packageDisplayName;
 
       // Put this doc into the appropriate list in the entry-point doc.
-      if (doc.isDirective) {
+      if (doc.isComponent) {
+        entryPoint.components.push(doc);
+      } else if (doc.isDirective) {
         entryPoint.directives.push(doc);
       } else if (doc.isService) {
         entryPoint.services.push(doc);
diff --git a/tools/dgeni/templates/class.template.html b/tools/dgeni/templates/class.template.html
index 68538ebcbdd2..c9a4859bfdde 100644
--- a/tools/dgeni/templates/class.template.html
+++ b/tools/dgeni/templates/class.template.html
@@ -17,18 +17,27 @@ <h4 id="{$ class.name $}" class="docs-header-link docs-api-h4 docs-api-class-nam
 <p class="docs-api-class-description">{$ class.description | marked | safe $}</p>
 {%- endif -%}
 
-{%- if class.directiveSelectors -%}
+{%- if class.selectors and class.isComponent -%}
+<p class="docs-api-component-selectors">
+  <span class="docs-api-class-selector-label">Selector:</span>
+  {% for selector in class.selectors %}
+    <span class="docs-api-class-selector-name">{$ selector $}</span>
+  {% endfor %}
+</p>
+{%- endif -%}
+
+{%- if class.selectors and class.isDirective -%}
 <p class="docs-api-directive-selectors">
   <span class="docs-api-class-selector-label">Selector:</span>
-  {% for selector in class.directiveSelectors %}
+  {% for selector in class.selectors %}
     <span class="docs-api-class-selector-name">{$ selector $}</span>
   {% endfor %}
 </p>
 {%- endif -%}
 
-{%- if class.directiveExportAs -%}
+{%- if class.exportAs -%}
 <span class="docs-api-class-export-label">Exported as:</span>
-<span class="docs-api-class-export-name">{$ class.directiveExportAs $}</span>
+<span class="docs-api-class-export-name">{$ class.exportAs $}</span>
 {%- endif -%}
 
 {%- if class.isDeprecated -%}
diff --git a/tools/dgeni/templates/entry-point.template.html b/tools/dgeni/templates/entry-point.template.html
index 6b70a5ae16d0..b5437ba42c5b 100644
--- a/tools/dgeni/templates/entry-point.template.html
+++ b/tools/dgeni/templates/entry-point.template.html
@@ -60,6 +60,15 @@ <h3 id="{$ doc.name $}-services" class="docs-header-link docs-api-h3">
     {% endfor %}
   {%- endif -%}
 
+  {%- if doc.components.length -%}
+    <h3 id="{$ doc.name $}-components" class="docs-header-link docs-api-h3">
+      <span header-link="components"></span>
+      Components
+    </h3>
+    {% for component in doc.components %}
+      {$ class(component) $}
+    {% endfor %}
+  {%- endif -%}
 
   {%- if doc.directives.length -%}
     <h3 id="{$ doc.name $}-directives" class="docs-header-link docs-api-h3">
diff --git a/tools/dgeni/templates/property.template.html b/tools/dgeni/templates/property.template.html
index ad20ffb1dae2..c9e94d06a564 100644
--- a/tools/dgeni/templates/property.template.html
+++ b/tools/dgeni/templates/property.template.html
@@ -2,19 +2,19 @@
 
 <tr class="docs-api-properties-row">
   <td class="docs-api-properties-name-cell">
-    {%- if property.isDirectiveInput -%}
+    {%- if property.isInput -%}
       <div class="docs-api-input-marker">
-        {%- if property.directiveInputAlias -%}
-        @Input(<span class="docs-api-input-alias">{$ property.directiveInputAlias $}</span>)
+        {%- if property.inputAlias -%}
+        @Input(<span class="docs-api-input-alias">{$ property.inputAlias $}</span>)
         {% else %}
           @Input()
         {%- endif -%}
       </div>
     {%- endif -%}
-    {%- if property.isDirectiveOutput -%}
+    {%- if property.isOutput -%}
       <div class="docs-api-output-marker">
-        {%- if property.directiveOutputAlias -%}
-        @Output(<span class="docs-api-output-alias">{$ property.directiveOutputAlias $}</span>)
+        {%- if property.outputAlias -%}
+        @Output(<span class="docs-api-output-alias">{$ property.outputAlias $}</span>)
         {% else %}
           @Output()
         {%- endif -%}