Merge pull request #1530 from roomman/patch-1

Reflect the introduction of Component Signatures

Author: chriskrycho

docs/ember/components.md

@@ -36,19 +36,46 @@ export default class Counter extends Component {
 
 Notice that there are no type declarations here – but this _is_ actually a well-typed component. The type of `count` is `number`, and if we accidentally wrote something like `this.count = "hello"` the compiler would give us an error.
 
-## Adding arguments
+## Adding arguments and giving them a type
 
 So far so good, but of course most components aren’t quite this simple! Instead, they’re invoked by other templates and they can invoke other components themselves in their own templates.
 
-Glimmer components can receive both _arguments_ and _attributes_ when they are invoked. When you are working with a component’s backing class, you have access to the arguments but _not_ to the attributes. The arguments are passed to the constructor, and then available as `this.args` on the component instance afterward. Let’s imagine a component which just logs the names of its arguments when it is first constructed:
+Glimmer components can receive both _arguments_ and _attributes_ when they are invoked. When you are working with a component’s backing class, you have access to the arguments but _not_ to the attributes. The arguments are passed to the constructor, and then available as `this.args` on the component instance afterward. 
+
+Since the implementation of [RFC 748], Glimmer and Ember components accept a `Signature` type parameter as part of their definition. This parameter is expected to be an object type with (up to) three members: `Args`, `Element` and `Blocks`.
+
+[rfc 748]: https://github.com/emberjs/rfcs/pull/748
+
+`Args` represents the arguments your component accepts. Typically this will be an object type mapping the names of your args to their expected type. For example:
+
+```
+export interface MySignature {
+  Args: {
+    arg1: string;
+    arg2: number;
+    arg3: boolean;
+  }
+}
+```
+If no `Args` key is specified, it will be a type error to pass any arguments to your component. You can read more about `Element` and `Block` in the Glint [Component Signatures documentation](https://typed-ember.gitbook.io/glint/using-glint/ember/component-signatures).
+
+Let’s imagine a component which just logs the names of its arguments when it is first constructed. First, we must define the Signature and pass it into our component, then we can use the `Args` member in our Signature to set the type of `args` in the constructor:
 
 ```typescript
 import Component from '@glimmer/component';
 
 const log = console.log.bind(console);
 
-export default class ArgsDisplay extends Component {
-  constructor(owner: unknown, args: {}) {
+export interface ArgsDisplaySignature {
+  Args: {
+    arg1: string;
+    arg2: number;
+    arg3: boolean;
+  }
+}
+
+export default class ArgsDisplay extends Component<ArgsDisplaySignature> {
+  constructor(owner: unknown, args: ArgsDisplaySignature['Args]) {
     super(owner, args);
 
     Object.keys(args).forEach(log);
@@ -69,24 +96,22 @@ Notice that we have to start by calling `super` with `owner` and `args`. This ma
 This might change in the future! If TypeScript eventually adds [support for “variadic kinds”](https://github.com/Microsoft/TypeScript/issues/5453), using `...arguments` could become safe.
 {% endhint %}
 
-The types for `owner` here and `args` line up with what the `constructor` for Glimmer components expect. The `owner` is specified as `unknown` because this is a detail we explicitly _don’t_ need to know about. The `args` are `{}` because a Glimmer component _always_ receives an object containing its arguments, even if the caller didn’t pass anything: then it would just be an empty object.
-
-`{}` is an empty object type – all objects extend from it, but there will be no properties on it. This is distinct from the `object` type, which the TypeScript docs describe as:
-
-> any thing that is not `number`, `string`, `boolean`, `symbol`, `null`, or `undefined`.
-
-If we used `object`, we could end up with TypeScript thinking `args` were an array, or a `Set`, or anything else that isn’t a primitive. Since we have `{}`, we _know_ that it's an object.
-
-{% hint style="info" %}
-For some further details, check out [this blog post](https://mariusschulz.com/blog/the-object-type-in-typescript).
-{% endhint %}
+The types for `owner` here and `args` line up with what the `constructor` for Glimmer components expect. The `owner` is specified as `unknown` because this is a detail we explicitly _don’t_ need to know about. The `args` are the `Args` from the Signature we defined.
 
 The `args` passed to a Glimmer Component [are available on `this`](https://github.com/glimmerjs/glimmer.js/blob/2f840309f013898289af605abffe7aee7acc6ed5/packages/%40glimmer/component/src/component.ts#L12), so we could change our definition to return the names of the arguments from a getter:
 
 ```typescript
 import Component from '@glimmer/component';
 
-export default class ArgsDisplay extends Component {
+export interface ArgsDisplaySignature {
+  Args: {
+    arg1: string;
+    arg2: number;
+    arg3: boolean;
+  }
+}
+
+export default class ArgsDisplay extends Component<ArgsDisplaySignature> {
   get argNames(): string[] {
     return Object.keys(this.args);
   }
@@ -192,4 +217,3 @@ export default class FancyInput<Args extends FancyInputArgs = FancyInputArgs> ex
 ```
 
 Requiring that `Args extends FancyInputArgs` means that subclasses can have _more_ than these args, but not _fewer_. Specifying that the `Args = FancyInputArgs` means that they _default_ to just being `FancyInputArgs`, so users don't need to supply an explicit generic type parameter here unless they're adding more arguments to the class.
-