From a426bdf4d510b4c0af0fa4e6bae556b3fda14e4e Mon Sep 17 00:00:00 2001
From: Matthieu Riegler <kyro38@gmail.com>
Date: Thu, 19 Dec 2024 01:46:31 +0100
Subject: [PATCH] docs: update class & style binding recommendation (#59240)

This commit introduces an update to the official recommendations when it comes to class & styles bindings.

`[class]` & `[style]` bindings are now recommended for basic uses cases.

`[ngClass]` and `[ngStyle]` allow more advanced bindings (like space separated keys) or keys with units (for `ngStyle`) which are not supported by the native bindings. They still require the dedicated directives.

PR Close #59240
---
 adev/src/content/guide/directives/overview.md |  2 ++
 packages/common/src/directives/ng_class.ts    | 27 ++++++++++++-------
 packages/common/src/directives/ng_style.ts    | 17 +++++++-----
 3 files changed, 30 insertions(+), 16 deletions(-)

diff --git a/adev/src/content/guide/directives/overview.md b/adev/src/content/guide/directives/overview.md
index 9c223f4858a..5e59ce2ce6c 100644
--- a/adev/src/content/guide/directives/overview.md
+++ b/adev/src/content/guide/directives/overview.md
@@ -69,6 +69,8 @@ These steps are not necessary to implement `ngClass`.
 
 ## Setting inline styles with `NgStyle`
 
+HELPFUL: To add or remove a _single_ style, use [style bindings](guide/templates/binding#css-class-and-style-property-bindings) rather than `NgStyle`.
+
 ### Import `NgStyle` in the component
 
 To use `NgStyle`, add it to the component's `imports` list.
diff --git a/packages/common/src/directives/ng_class.ts b/packages/common/src/directives/ng_class.ts
index ddc81c9c154..80db9c3da8d 100644
--- a/packages/common/src/directives/ng_class.ts
+++ b/packages/common/src/directives/ng_class.ts
@@ -10,8 +10,6 @@ import {
   DoCheck,
   ElementRef,
   Input,
-  IterableDiffers,
-  KeyValueDiffers,
   Renderer2,
   ɵstringify as stringify,
 } from '@angular/core';
@@ -43,17 +41,23 @@ interface CssClassState {
  *
  * @usageNotes
  * ```html
- *     <some-element [ngClass]="'first second'">...</some-element>
+ * <some-element [ngClass]="stringExp|arrayExp|objExp|Set">...</some-element>
  *
- *     <some-element [ngClass]="['first', 'second']">...</some-element>
- *
- *     <some-element [ngClass]="{'first': true, 'second': true, 'third': false}">...</some-element>
- *
- *     <some-element [ngClass]="stringExp|arrayExp|objExp">...</some-element>
- *
- *     <some-element [ngClass]="{'class1 class2 class3' : true}">...</some-element>
+ * <some-element [ngClass]="{'class1 class2 class3' : true}">...</some-element>
  * ```
  *
+ * For more simple use cases you can use the [class bindings](/guide/templates/binding#css-class-and-style-property-bindings) directly.
+ * It doesn't require importing a directive.
+ *
+ * ```html
+ * <some-element [class]="'first second'">...</some-element>
+ *
+ * <some-element [class.expanded]="isExpanded">...</some-element>
+ *
+ * <some-element [class]="['first', 'second']">...</some-element>
+ *
+ * <some-element [class]="{'first': true, 'second': true, 'third': false}">...</some-element>
+ * ```
  * @description
  *
  * Adds and removes CSS classes on an HTML element.
@@ -64,6 +68,9 @@ interface CssClassState {
  * - `Object` - keys are CSS classes that get added when the expression given in the value
  *              evaluates to a truthy value, otherwise they are removed.
  *
+ *
+ * @see [Class bindings](/guide/templates/binding#css-class-and-style-property-bindings)
+ *
  * @publicApi
  */
 @Directive({
diff --git a/packages/common/src/directives/ng_style.ts b/packages/common/src/directives/ng_style.ts
index 4a48e1a0079..5e8ef0b319d 100644
--- a/packages/common/src/directives/ng_style.ts
+++ b/packages/common/src/directives/ng_style.ts
@@ -22,12 +22,6 @@ import {
  *
  * @usageNotes
  *
- * Set the font of the containing element to the result of an expression.
- *
- * ```html
- * <some-element [ngStyle]="{'font-style': styleExp}">...</some-element>
- * ```
- *
  * Set the width of the containing element to a pixel value returned by an expression.
  *
  * ```html
@@ -40,6 +34,15 @@ import {
  * <some-element [ngStyle]="objExp">...</some-element>
  * ```
  *
+ * For more simple use cases you can use the [style bindings](/guide/templates/binding#css-class-and-style-property-bindings) directly.
+ * It doesn't require importing a directive.
+ *
+ * Set the font of the containing element to the result of an expression.
+ *
+ * ```html
+ * <some-element [style]="{'font-style': styleExp}">...</some-element>
+ * ```
+ *
  * @description
  *
  * An attribute directive that updates styles for the containing HTML element.
@@ -51,6 +54,8 @@ import {
  * is assigned to the given style property.
  * If the result of evaluation is null, the corresponding style is removed.
  *
+ * @see [Style bindings](/guide/templates/binding#css-class-and-style-property-bindings)
+ *
  * @publicApi
  */
 @Directive({