Documenting the TOC type (convenience alias for TemplateOnlyComponent)

[lukasnys]

I've mostly been using the TOC syntax to define template-only components. However, I noticed there wasn't any official documentation for this. (https://typed-ember.gitbook.io/glint/environments/ember/template-only-components)

I eagerly created #640 before reading the contribution guidelines so now I'm here to check if this is something we want to add to the documentation?

[dfreeman]

You're suggesting we tell users they can write declare const Foo: TOC<FooSignature> rather than const Foo = templateOnlyComponent<FooSignature>()?

What's the motivation for that? It's probably not something we want to recommend, as it could have bad interactions with ember-cli-htmlbars and ensuring that an actual templateOnlyComponent() call gets generated.

[lukasnys]

Yes, that's what I was suggesting indeed, but I probably understood the convenience type TOC wrong. My bad!

However, when using template tag components, would using the TOC type be fine or is it also recommended to use templateOnlyComponent() somehow?

e.g.

export const Foo: TOC<FooSignature> = <template> ... </template>;

or is there a way to do the same using the templateOnlyComponent() call?

[dfreeman]

TOC is a type, and templateOnlyComponent is a function. The two are related, but neither is an alias or shorthand for the other.

TOC, like all types, only exists during typechecking and goes away when your code is turned into JS to run in the browser. templateOnlyComponent() provides a runtime value, and you can think of it as an alternative to class extends Component as providing a backing context to your template. When the ember-cli build finds a .hbs file with no corresponding .js/.ts file, it implicitly creates a templateOnlyComponent call to act as the backing context for your component.

<template>, like templateOnlyComponent, is a runtime expression (in fact, the former uses the latter under the covers when it's not embedded in a class body). The TOC type is the type of value returned by templateOnlyComponent. In this code, a and b are equivalent:

const a: TOC<FooSignature> = templateOnlyComponent();
const b = templateOnlyComponent<FooSignature>();

The difference with <template> is that we don't (yet) have a first-class way of specifying a signature type directly as part of the <template> expression. You could imagine a syntax like <template type:signature={FooSignature}> that would be comparable to what we're doing with const b above, i.e. setting the signature directly, but since that doesn't exist yet, the only option is the const a version where we set the type as part of the variable declaration rather than within the expression itself.

[lukasnys]

Thanks for the super clear and insightful answer! This makes a lot of sense to me now.

Regarding the last paragraph: do you feel that we want to document the fact that users should use const a: TOC<FooSignature> = <template> ... </template> when using ember-template-imports (since there isn't yet a way to set the signature directly in the <template> tag)? If so, I'll update the PR to do so.

If you feel this isn't necessary I'll close the PR.

[dfreeman]

@lukasnys Capturing that somewhere does feel valuable! Instead of including it in the template-only components content, though, I think it probably makes the most sense in the context of a dedicated template-imports page (which I was surprised to discover just now doesn't already exist!)

If you'd be up for updating your PR to do that, that would be much appreciated! If that's more work than you bargained for, though, I totally understand, and we should probably just open an issue to track adding a Template Imports page to the docs.

[lukasnys]

@dfreeman I had a go at it on #647. Let me know if this aligns with what you had in mind!