new 9.1.7 content on structural-directives is unfinished?

📚 Docs or angular.io bug report

Description

https://angular.io/guide/structural-directives#make-in-template-type-requirements-more-specific-with-template-guards

IfLoadedDirective missing lines and is very difficult to understand.

🔬 Minimal Reproduction

What’s the affected URL?**

https://angular.io/guide/structural-directives#make-in-template-type-requirements-more-specific-with-template-guards

Reproduction Steps**

The content:

export type Loaded = { type: 'loaded', data: T };
export type Loading = { type: 'loading' };
export type LoadingState = Loaded | Loading;
export class IfLoadedDirective {
    @Input('ifLoaded') set state(state: LoadingState) {}
    static ngTemplateGuard_state(dir: IfLoadedDirective, expr: LoadingState): expr is Loaded { return true; };
export interface Person {
  name: string;
}

@Component({
  template: `{{ state.data }}`,
})
export class AppComponent {
  state: LoadingState;
}

Expected vs Actual Behavior**

expecting valid typescript that follows angular style guide

[JoostK]

Hi @bbarry, the language service is currently being updated to work identically to the real compilation, including type guards. This is still work in progress and not yet available.

[bbarry]

I have been able to get the context guard working at compilation but it doesn’t appear correct according to VsCode still.

My full working code is:

export class NgLetContext<T = any> {
  $implicit: T = null!; 
  ngLet: T = null!;
}

@Directive({
  selector: '[ngLet]',
})
export class NgLetDirective<T> implements OnInit {
  private _context = new NgLetContext<T>();

  @Input()
  set ngLet(value: T) {
    this._context.$implicit = this._context.ngLet = value;
  }

  constructor(private _vcr: ViewContainerRef, private _templateRef: TemplateRef<NgLetContext>) {}

  static ngTemplateContextGuard<T>(dir: NgLetDirective<T>, ctx: unknown): ctx is NgLetContext<T> {
    return true;
  }

  ngOnInit() {
    this._vcr.createEmbeddedView(this._templateRef, this._context);
  }
}

ng serve now correctly reports template errors. My editor (Vs Code) still has an any type for the value though and if I change NgLetContext<T = any> to NgLetContext<T = unknown> I get language service errors.

I believe this is due to a bug in the language service though, perhaps https://github.com/angular/vscode-ng-language-service/issues/880

---

On the issue here of documentation, it looks like this page has been updated with working code at least. Should this be closed?

I think it could be more clear. For example the title section

You can improve template type checking for custom directives by adding template guard properties to your directive definition. These properties help the Angular template type checker find mistakes in the template at compile time, which can avoid runtime errors those mistakes can cause.

Use the type-guard properties to inform the template type checker of an expected type, thus improving compile-time type-checking for that template.

• A property ngTemplateGuard_(someInputProperty) lets you specify a more accurate type for an input expression within the template.
• The ngTemplateContextGuard static property declares the type of the template context.

This section provides example of both kinds of type-guard property.

For more information, see Template type checking guide.

describes these properties and directs you to a page seemingly for more information, but the only lines on that page with relevant “more information” are links back to this section:

You can avoid run-time type errors by providing more specific in-template type requirements to the template type checker. Make the input type requirements for your own directives as specific as possible by providing template-guard functions in the directive definition. See Improving template type checking for custom directives, and Input setter coercion in this guide.

(irrelevant link not copied here) and

As a library author, you can take several measures to provide an optimal experience for your users. First, enabling strictNullChecks and including null in an input’s type, as appropriate, communicates to your consumers whether they can provide a nullable value or not. Additionally, it is possible to provide type hints that are specific to the template type checker. See Improving template type checking for custom directives, and Input setter coercion below.

I think it would be better if the directive relevant properties were all in the template type checking guide and not in the structural directives page at all. All that the structural directives page should say on the matter is that there are applications of type checking for structural directives and direct the user to the type check guide which should talk about both template guard properties and input coercion (which are really very similar things and have similar solutions).