From 1b56f294fcecebf313797df5fc6387aaa1796e78 Mon Sep 17 00:00:00 2001
From: Ruslan Lekhman <lekhman112@gmail.com>
Date: Mon, 13 Oct 2025 19:14:50 -0600
Subject: [PATCH] docs: improve properties and methods template

close #32060
---
 docs/src/styles/_api.scss                     |   1 +
 docs/src/styles/_tables.scss                  |  32 ++++
 tools/dgeni/templates/method.template.html    | 146 +++++++++---------
 .../templates/property-list.template.html     |  20 +--
 tools/dgeni/templates/property.template.html  |   2 +-
 5 files changed, 122 insertions(+), 79 deletions(-)

diff --git a/docs/src/styles/_api.scss b/docs/src/styles/_api.scss
index a6a4cebbaa6a..edac76cc0f79 100644
--- a/docs/src/styles/_api.scss
+++ b/docs/src/styles/_api.scss
@@ -98,6 +98,7 @@
   .docs-api-method-parameters-header-cell,
   .docs-api-method-returns-header-cell {
     font-size: 14px;
+    padding-bottom: 0;
   }
 
   .docs-api-input-marker,
diff --git a/docs/src/styles/_tables.scss b/docs/src/styles/_tables.scss
index c9084474be8b..aee301ef45e1 100644
--- a/docs/src/styles/_tables.scss
+++ b/docs/src/styles/_tables.scss
@@ -52,6 +52,38 @@
     height: 56px;
   }
 
+  .docs-api-method-card,
+  .docs-api-properties-card {
+    background-color: var(--mat-sys-surface-container-lowest);
+    border: solid 1px var(--mat-sys-outline-variant);
+    border-radius: 12px;
+    margin: 0 0 32px;
+  }
+
+  .docs-api-method-table,
+  .docs-api-properties-table {
+    margin: 0 !important;
+  }
+
+  .docs-api-method-table tr {
+    border-bottom: 0;
+
+    th.docs-api-method-name-cell .docs-api-method-parameter-name {
+      color: var(--mat-sys-on-surface);
+    }
+  }
+
+  .docs-api-properties-table {
+    .docs-api-properties-row:last-of-type {
+      border-bottom: 0;
+    }
+
+    .docs-api-property-type {
+      color: var(--mat-sys-primary);
+    }
+  }
+
+
   @media (max-width: constants.$small-breakpoint-width) {
     .docs-api table,
     .docs-markdown > table {
diff --git a/tools/dgeni/templates/method.template.html b/tools/dgeni/templates/method.template.html
index 392f544861b5..771953ef73ca 100644
--- a/tools/dgeni/templates/method.template.html
+++ b/tools/dgeni/templates/method.template.html
@@ -1,77 +1,85 @@
 {% import "macros.html" as macros %}
 
-<table class="docs-api-method-table">
-  <thead>
-    <tr class="docs-api-method-name-row">
-      <th colspan="2" class="docs-api-method-name-cell">
-        {%- if method.isDeprecated -%}
-          <div class="docs-api-deprecated-marker" {$ macros.deprecationTitle(method) $}>
-            Deprecated
+<div class="docs-api-method-card">
+  <table class="docs-api-method-table">
+    <thead>
+      <tr class="docs-api-method-name-row">
+        <th colspan="2" class="docs-api-method-name-cell">
+          {%- if method.isDeprecated -%}
+            <div class="docs-api-deprecated-marker" {$ macros.deprecationTitle(method) $}>
+              Deprecated
+            </div>
+          {%- endif -%}
+          {%- if method.isStatic -%}
+          <div class="docs-api-modifier-method-marker">
+            static
           </div>
-        {%- endif -%}
-        {%- if method.isStatic -%}
-        <div class="docs-api-modifier-method-marker">
-          static
-        </div>
-        {%- endif -%}
-        {%- if method.isAsync -%}
-        <div class="docs-api-modifier-method-marker">
-          async
-        </div>
-        {%- endif -%}
-        {$ method.name $}
-      </th>
+          {%- endif -%}
+          {%- if method.isAsync -%}
+          <div class="docs-api-modifier-method-marker">
+            async
+          </div>
+          {%- endif -%}
+          {$ method.name $}
+          ({%- for param in method.params -%}
+            <span class="docs-api-method-parameter-name">{$ param.name $}{% if param.isOptional %}<span class="docs-api-method-parameter-optional-marker">?</span>{% endif %}:
+            </span>
+            <code class="docs-api-method-parameter-type">{$ param.type $}</code>{% if not loop.last %}, {% endif %}
+          {%- endfor -%}
+          ): <code class="docs-api-method-returns-type">{$ method.type $}</code>
+        </th>
+      </tr>
+    </thead>
+    {%- if method.description -%}
+    <tr class="docs-api-method-description-row">
+      <td colspan="2" class="docs-api-method-description-cell">
+        {$ method.description | marked | safe $}
+      </td>
     </tr>
-  </thead>
-  {%- if method.description -%}
-  <tr class="docs-api-method-description-row">
-    <td colspan="2" class="docs-api-method-description-cell">
-      {$ method.description | marked | safe $}
-    </td>
-  </tr>
-  {%- endif -%}
+    {%- endif -%}
 
-  {%- if method.params.length -%}
-  <thead>
-    <tr class="docs-api-method-parameters-header-row">
-      <th colspan="2" class="docs-api-method-parameters-header-cell">Parameters</th>
+    {%- if method.params.length -%}
+    <thead>
+      <tr class="docs-api-method-parameters-header-row">
+        <th colspan="2" class="docs-api-method-parameters-header-cell">Parameters</th>
+      </tr>
+    </thead>
+    {% for parameter in method.params %}
+    <tr class="docs-api-method-parameter-row">
+      <td class="docs-api-method-parameter-cell">
+        <p class="docs-api-method-parameter-name">
+          {$ parameter.name $}
+          {%- if parameter.isOptional -%}
+            <span class="docs-api-method-parameter-optional-marker">?</span>
+          {%- endif -%}
+        </p>
+        <code class="docs-api-method-parameter-type">{$ parameter.type $}</code>
+      </td>
+      <td class="docs-api-method-parameter-description-cell">
+        <p class="docs-api-method-parameter-description">
+          {$ parameter.description | marked | safe $}
+        </p>
+      </td>
     </tr>
-  </thead>
-  {% for parameter in method.params %}
-  <tr class="docs-api-method-parameter-row">
-    <td class="docs-api-method-parameter-cell">
-      <p class="docs-api-method-parameter-name">
-        {$ parameter.name $}
-        {%- if parameter.isOptional -%}
-          <span class="docs-api-method-parameter-optional-marker">?</span>
-        {%- endif -%}
-      </p>
-      <code class="docs-api-method-parameter-type">{$ parameter.type $}</code>
-    </td>
-    <td class="docs-api-method-parameter-description-cell">
-      <p class="docs-api-method-parameter-description">
-        {$ parameter.description | marked | safe $}
-      </p>
-    </td>
-  </tr>
-  {% endfor %}
-  {%- endif -%}
+    {% endfor %}
+    {%- endif -%}
 
-  {%- if method.type and method.type !== "void" -%}
-  <thead>
-    <tr class="docs-api-method-returns-header-row">
-      <th colspan="2" class="docs-api-method-returns-header-cell">Returns</th>
+    {%- if method.type and method.type !== "void" -%}
+    <thead>
+      <tr class="docs-api-method-returns-header-row">
+        <th colspan="2" class="docs-api-method-returns-header-cell">Returns</th>
+      </tr>
+    </thead>
+    <tr>
+      <td class="docs-api-method-returns-type-cell">
+        <code class="docs-api-method-returns-type">{$ method.type $}</code>
+      </td>
+      <td class="docs-api-method-returns-description-cell">
+        <p class="docs-api-method-returns-description">
+          {$ method.returns.description | marked | safe $}
+        </p>
+      </td>
     </tr>
-  </thead>
-  <tr>
-    <td class="docs-api-method-returns-type-cell">
-      <code class="docs-api-method-returns-type">{$ method.type $}</code>
-    </td>
-    <td class="docs-api-method-returns-description-cell">
-      <p class="docs-api-method-returns-description">
-        {$ method.returns.description | marked | safe $}
-      </p>
-    </td>
-  </tr>
-  {%- endif -%}
-</table>
+    {%- endif -%}
+  </table>
+</div>
diff --git a/tools/dgeni/templates/property-list.template.html b/tools/dgeni/templates/property-list.template.html
index 0a54b03a629d..874c2cc91c96 100644
--- a/tools/dgeni/templates/property-list.template.html
+++ b/tools/dgeni/templates/property-list.template.html
@@ -1,12 +1,14 @@
 {%- if propertyList.length -%}
   <h5 class="docs-api-h5 docs-api-method-header">Properties</h5>
-  <table class="docs-api-properties-table">
-    <tr class="docs-api-properties-header-row">
-      <th class="docs-api-properties-th">Name</th>
-      <th class="docs-api-properties-th">Description</th>
-    </tr>
-    {% for p in propertyList %}
-      {$ property(p) $}
-    {% endfor %}
-  </table>
+  <div class="docs-api-properties-card">
+    <table class="docs-api-properties-table">
+      <tr class="docs-api-properties-header-row">
+        <th class="docs-api-properties-th">Name</th>
+        <th class="docs-api-properties-th">Description</th>
+      </tr>
+      {% for p in propertyList %}
+        {$ property(p) $}
+      {% endfor %}
+    </table>
+  </div>
 {%- endif -%}
diff --git a/tools/dgeni/templates/property.template.html b/tools/dgeni/templates/property.template.html
index c9e94d06a564..155bb6348330 100644
--- a/tools/dgeni/templates/property.template.html
+++ b/tools/dgeni/templates/property.template.html
@@ -27,7 +27,7 @@
     {%- endif -%}
 
     <p class="docs-api-property-name">
-      <code>{%- if property.isStatic -%}static&nbsp;{%- endif -%}{$ property.name $}: {$ property.type $}</code>
+      <code>{%- if property.isStatic -%}static&nbsp;{%- endif -%}{$ property.name $}: <code class="docs-api-property-type">{$ property.type $}</code></code>
     </p>
   </td>
   <td class="docs-api-property-description">{$ property.description | marked | safe $}</td>