Merge pull request #647 from lukasnys/docs-template-imports

docs/contents.md

@@ -23,6 +23,7 @@
   * [Rendering Tests](ember/rendering-tests.md)
   * [Using Addons](ember/using-addons.md)
   * [Authoring Addons](ember/authoring-addons.md)
+  * [Template Imports](ember/template-imports.md)
 * [GlimmerX](using-glint/glimmerx/README.md)
   * [Installation](glimmerx/installation.md)
   * [Component Signatures](glimmerx/component-signatures.md)

docs/ember/installation.md

@@ -35,27 +35,13 @@ npm install -D @glint/core @glint/template @glint/environment-ember-loose
 
 {% endcode %}
 
-<details>
+{% hint style="info" %}
 
-<summary>Using ember-template-imports?</summary>
+Using `ember-template-imports`? See [Ember: Template Imports][etii] for additional installation steps.
 
-If you are using `ember-template-imports` in your project, you also need to install the `@glint/environment-ember-template-imports` package and configure it in `tsconfig.json` under `glint.environment`:
+[etii]: ../ember/template-imports.md#installation
 
-{% code title="tsconfig.json" %}
-```json
-{
-  "compilerOptions": { /* ... */ },
-  "glint": {
-    "environment": [
-      "ember-loose",
-      "ember-template-imports",
-    ]
-  }
-}
-```
-{% endcode %}
-
-</details>
+{% endhint %}
 
 Note that, by default, Glint will assume you want it to analyze all templates in the codebase that are covered by your `tsconfig.json`. To ignore any type errors up front so that you can incrementally migrate your project to typesafe templates, consider using [the `auto-glint-nocheck` script](https://github.com/typed-ember/glint/tree/main/packages/scripts#auto-glint-nocheck) to add [`@glint-nocheck` comments](../directives.md#glint-nocheck) to your existing templates that would produce errors.
 
@@ -65,12 +51,6 @@ Finally, ensure you've added the following statement somewhere in your project's
 import '@glint/environment-ember-loose';
 ```
 
-If using `ember-template-imports`, add a corresponding line for that environment as well:
-
-```typescript
-import '@glint/environment-ember-template-imports';
-```
-
 You may also choose to disable TypeScript's "unused symbol" warnings in your editor, since Glint will flag any symbols that are actually unused, while `tsserver` won't understand any symbol usage that only occurs in templates.
 
 {% hint style="info" %}

docs/ember/template-imports.md

@@ -0,0 +1,73 @@
+When adding Glint to an Ember project with `ember-template-imports` installed, there are a few additional things to consider.
+
+## Installation
+
+In addition to the `@glint/core`, `@glint/template` and `@glint/environment-ember-loose` packages, you also need to install the `@glint/environment-ember-template-imports` package and configure it in `tsconfig.json` under `glint.environment`:
+
+{% tabs %}
+{% tab title="Yarn" %}
+
+```sh
+yarn add --dev @glint/core @glint/template @glint/environment-ember-loose @glint/environment-ember-template-imports
+```
+
+{% endtab %}
+{% tab title="npm" %}
+
+```sh
+npm install -D @glint/core @glint/template @glint/environment-ember-loose @glint/environment-ember-template-imports
+```
+
+{% endtab %}
+{% endtabs %}
+
+{% code title="tsconfig.json" %}
+
+```javascript
+{
+  "compilerOptions": { /* ... */ },
+  "glint": {
+    "environment": [
+      "ember-loose",
+      "ember-template-imports",
+    ]
+  }
+}
+```
+
+Additionally, ensure you've added the following statement somewhere in your project's source files or ambient type declarations:
+
+```typescript
+import '@glint/environment-ember-template-imports';
+```
+
+{% endcode %}
+
+## Template-Only Components
+
+When using `ember-template-imports`, you can declare the type of a `<template>` component using the `TOC` type:
+
+{% code title="app/components/shout.gts %}
+
+```typescript
+import type { TOC } From '@ember/component/template-only';
+
+interface ShoutSignature {
+  Element: HTMLDivElement;
+  Args: { message: string };
+  Blocks: {
+    default: [shoutedMessage: string];
+  };
+}
+
+const louderPlease = (message: string) => message.toUpperCase();
+
+const Shout: TOC<ShoutSignature> = <template>
+    <div ...attributes>
+        {{yield (louderPlease @message)}}
+    </div>
+</template>;
+export default Shout;
+```
+
+{% endcode %}

docs/ember/template-only-components.md

@@ -26,6 +26,13 @@ declare module '@glint/environment-ember-loose/registry' {
 
 Note that the runtime content of this module (effectively `export default templateOnlyComponent();`) is exactly what Ember generates at build time when creating a backing module for a template-only component.
 
+{% hint style="info" %}
+
+Using `ember-template-imports`? See [Ember: Template Imports][etitoc] on how to declare types for a `<template>`-only component.
+
+[etitoc]: ../ember/template-imports.md#template-only-components
+{% endhint %}
+
 Due to the way TypeScript works, it's not possible to have a generic signature for template-only components:
 
 ```typescript