docs: add mentions host style bindings (angular#64257)

Also adds a section about css custom properties

fixes angular#64256

PR Close angular#64257

Author: JeanMeche

adev/shared-docs/pipeline/shared/linking.mts

@@ -9,7 +9,8 @@
 // In some case we know that we don't want to link a symbol
 // Example when there is a conflict between API entries and compiler features.
 // eg: "animate" is both an Animation API entry and an template instruction "animation.enter"
-const LINK_EXEMPT = new Set(['animate', 'animate.enter', 'animate.leave']);
+// or "style" is a generic term but also an Animation API entry.
+const LINK_EXEMPT = new Set(['animate', 'animate.enter', 'animate.leave', 'style']);
 
 export function shouldLinkSymbol(symbol: string): boolean {
   return !LINK_EXEMPT.has(symbol);

adev/src/content/guide/components/host-elements.md

@@ -37,7 +37,7 @@ In the above example, `<profile-photo>` is the host element of the `ProfilePhoto
 
 ## Binding to the host element
 
-A component can bind properties, attributes, and events to its host element. This behaves
+A component can bind properties, attributes, styles and events to its host element. This behaves
 identically to bindings on elements inside the component's template, but instead defined with
 the `host` property in the `@Component` decorator:
 
@@ -48,6 +48,7 @@ the `host` property in the `@Component` decorator:
     'role': 'slider',
     '[attr.aria-valuenow]': 'value',
     '[class.active]': 'isActive()',
+    '[style.background] : `hasError() ? 'red' : 'green'`,
     '[tabIndex]': 'disabled ? -1 : 0',
     '(keydown)': 'updateValue($event)',
   },
@@ -56,6 +57,7 @@ export class CustomSlider {
   value: number = 0;
   disabled: boolean = false;
   isActive = signal(false);
+  hasError = signal(false);
   updateValue(event: KeyboardEvent) { /* ... */ }
 
   /* ... */
@@ -98,8 +100,10 @@ export class CustomSlider {
 }
 ```
 
-**Always prefer using the `host` property over `@HostBinding` and `@HostListener`.** These
+<docs-callout critical title="Prefer using the `host` property over the decorators">
+  **Always prefer using the `host` property over `@HostBinding` and `@HostListener`.** These
 decorators exist exclusively for backwards compatibility.
+</docs-callout>
 
 ## Binding collisions
 
@@ -126,3 +130,36 @@ In cases like this, the following rules determine which value wins:
 - If both values are static, the instance binding wins.
 - If one value is static and the other dynamic, the dynamic value wins.
 - If both values are dynamic, the component's host binding wins.
+
+## Styling with CSS custom properties
+
+Developers often rely on [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties) to enable a flexible configuration of their component's styles.
+You can set such custom properties on a host element with a [style binding][style binding](guide/templates/binding#css-style-properties).
+
+```angular-ts
+@Component({
+  /* ... */
+  host: {
+    '[style.--my-background]': 'color()',
+  }
+})
+export class MyComponent {
+  color = signal('lightgreen');
+}
+```
+
+In this example, the `--my-background` CSS custom property is bound to the `color` signal. The value of the custom property will automatically update whenever the `color` signal changes. This will affect the current component and all its children that rely on this custom property.
+
+### Setting custom properties on children compoents
+
+Alternatively, it is also possible to set css custom properties on the host element of children components with a [style binding](guide/templates/binding#css-style-properties).
+
+```angular-ts
+@Component({
+  selector: 'my-component',
+  template: `<my-child [style.--my-background]="color()">`,
+})
+export class MyComponent {
+  color = signal('lightgreen');
+}
+```

packages/core/src/metadata/directives.ts

@@ -925,6 +925,9 @@ export interface HostBindingDecorator {
    *
    * @usageNotes
    *
+   * NOTE:  **Always** prefer using the `host` property over `@HostBinding`.
+   * This decorator exist exclusively for backwards compatibility.
+   *
    * The following example creates a directive that sets the `valid` and `invalid`
    * class, a style color, and an id on the DOM element that has an `ngModel` directive on it.
    *