Add Glint to the project

chriskrycho · chriskrycho · commit 41c752493e58 · 2022-11-19T15:27:17.000-07:00
This adds basic [Glint]-powered capabilities to the project for anyone using a Glint Language Server client (VS Code, NeoVim, IntelliJ, etc.). Setup ----- The setup to make that work involves adding some `devDependencies`: - `@glint/core` to enable Glint and `@glint/environment-ember-loose` to tell Glint how to interpret Ember's "loose-mode" templates, i.e. "normal" - `typescript`, which Glint requires to work at all. **This is _not_ adding TypeScript to the project.** It just exists to enable Glint to run. (Glint doesn't ship its own copy because TypeScript is large and it is important that Glint use the same version of TypeScript that an app uses, or else it would give conflicting reports.) - A number of `@types` packages, which are required so that Glint knows what a `Controller` or Ember `Component` are, and so on. These will all be able to go away as packages start shipping their own types, including when this app is able to upgrade to at least Ember 4.8 and start using the types that Ember ships itself. It also configures Glint via tweaks to the existing `jsconfig.json` file, with good defaults so that it never shows *errors*, but does progressively enhance the experience for JS users. Other changes ------------- With the foundations in place, add some JSDoc comments and a single TS file to the project. - The JSDoc comments show how to make TS-powered tooling (like the various Glint language servers) understand components in the app. These comments, which build on the spec for both types and comments defined in [Ember RFC 0748][rfc], work well to enhance the experience of authoring JS backing classes even *without* Glint. With Glint enabled, though, it also makes all of that information available in templates. - The TS file shows how to make Glint understand component references. It is basically a hand-coded version of what the Ember resolver does at runtime: translating string names like `MyComponent` into references to the `MyComponent` class. There are limitations to how much this can do in a purely JS project with loose mode templates, but in this app it can cover *most* of the territory (and a move to strict mode templates using `<template>` in the future will close *all* of those gaps). Both of these show the "progressive enhancement" model at work: out of the box, you get a *very* minimal set of go-to-definition, refactoring, etc. capabilities. Not none! But minimal. The more fino you put into your JSDoc comments, though, and the more items you add to the template registry, the more useful Glint becomes. [rfc]: https://rfcs.emberjs.com/id/0748-glimmer-component-signature Caveats ------- This does not yet provide *all* the benefits that Glint can provide to JS-only apps. For example, you won't be able to go-to-definition for the `this.model` of route/controller templates unless you add a `model` field on the `Controller` class with a JSDoc annotation. Similarly, you will not be able to go-to-definition or see hover docs for a lot of the data used in the application just yet: the app will need to add some JSDoc annotations to tell the language server "this field here is that data model class from over there". However, it *does* already provide significant benefits for simple things like being able to go to definition or rename items in component files, and as the one JSDoc annotation added in this shows, you can get more of these benefits with a very low level of effort. [Glint]: https://github.com/typed-ember/glint
diff --git a/app/components/api-index-filter.js b/app/components/api-index-filter.js
@@ -7,6 +7,20 @@ import sortBy from 'lodash.sortby';
 const filterDataComputedParams =
   'filterData.{showInherited,showProtected,showPrivate,showDeprecated}';
 
+/**
+ * @typedef Args
+ * @property {object} model
+ * @property {object} filterData
+ */
+
+/**
+ * @typedef Blocks
+ * @property {[ApiIndexFilter['filteredData']]} default
+ */
+
+/**
+ * @extends Component<{ Args: Args, Blocks: Blocks }>
+ */
 @classNames('api-index-filter')
 export default class ApiIndexFilter extends Component {
   @computed('model.methods.[]', filterDataComputedParams)
diff --git a/app/components/api-index.js b/app/components/api-index.js
@@ -1,29 +1,46 @@
-/* eslint-disable ember/no-computed-properties-in-native-classes */
-import { computed } from '@ember/object';
-import Component from '@ember/component';
+import Component from '@glimmer/component';
 
+/**
+ * @typedef ItemData
+ * @property {Array<{ name: string }>} methods
+ * @property {Array<{ name: string }>} properties
+ * @property {Array<{ name: string }>} events
+ */
+
+/**
+ * @typedef Args
+ * @property {ItemData} itemData
+ */
+
+/**
+ * @typedef Blocks
+ * @property {[{ sections: ApiIndex['sections'] }]} default
+ */
+
+/**
+ * @extends Component<{ Args: Args, Blocks: Blocks }>
+ */
 export default class ApiIndex extends Component {
-  @computed('itemData.{methods,properties,events}')
   get sections() {
     return [
       {
         title: 'Methods',
         tab: 'methods',
-        items: this.itemData.methods,
+        items: this.args.itemData.methods,
         class: 'spec-method-list',
         routeSuffix: '.methods.method',
       },
       {
         title: 'Properties',
         tab: 'properties',
-        items: this.itemData.properties,
+        items: this.args.itemData.properties,
         class: 'spec-property-list',
         routeSuffix: '.properties.property',
       },
       {
         title: 'Events',
         tab: 'events',
-        items: this.itemData.events,
+        items: this.args.itemData.events,
         class: 'spec-event-list',
         routeSuffix: '.events.event',
       },
diff --git a/app/registry.d.ts b/app/registry.d.ts
@@ -0,0 +1,9 @@
+import ApiIndex from './components/api-index';
+import ApiIndexFilter from './components/api-index-filter';
+
+declare module '@glint/environment-ember-loose/registry' {
+  export default interface Registry {
+    ApiIndex: typeof ApiIndex;
+    ApiIndexFilter: typeof ApiIndexFilter;
+  }
+}
diff --git a/app/templates/class-index.hbs b/app/templates/class-index.hbs
@@ -6,7 +6,15 @@
         <ul class="{{section.class}}">
           {{#each section.items as |item|}}
             <li data-test-item={{item.name}}>
-              <LinkTo @route={{concat this.parentName section.routeSuffix }} @models={{array @model.project.id @model.projectVersion.compactVersion @model.name item.name}} @query={{hash anchor=item.name}}>
+              <LinkTo
+                @route="{{this.parentName}}{{section.routeSuffix}}"
+                @models={{array
+                  @model.project.id
+                  @model.projectVersion.compactVersion
+                  @model.name item.name
+                }}
+                @query={{hash anchor=item.name}}
+              >
                 {{item.name}}
               </LinkTo>
             </li>
diff --git a/app/templates/components/api-index.hbs b/app/templates/components/api-index.hbs
@@ -1,3 +1,5 @@
+<div>
 {{yield (hash
   sections=this.sections)
 }}
+</div>
diff --git a/jsconfig.json b/jsconfig.json
@@ -1,5 +1,15 @@
 {
-    "compilerOptions": {
-      "experimentalDecorators": true
-    },
-}
+  "extends": "@tsconfig/ember",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "ember-api-docs/*": [
+        "app/*"
+      ]
+    }
+  },
+  "glint": {
+    "environment": "ember-loose",
+    "checkStandaloneTemplates": false
+  }
+}
diff --git a/package.json b/package.json
@@ -30,8 +30,26 @@
     "@ember/test-helpers": "^2.2.5",
     "@glimmer/component": "^1.0.0",
     "@glimmer/tracking": "^1.0.0",
+    "@glint/core": "^0.9.7",
+    "@glint/environment-ember-loose": "^0.9.7",
     "@percy/cli": "^1.0.0-beta.54",
     "@percy/ember": "^3.0.0",
+    "@tsconfig/ember": "^1.0.1",
+    "@types/ember": "^4.0.2",
+    "@types/ember-qunit": "^5.0.2",
+    "@types/ember-resolver": "^5.0.13",
+    "@types/ember__application": "^4.0.4",
+    "@types/ember__array": "^4.0.3",
+    "@types/ember__component": "^4.0.11",
+    "@types/ember__controller": "^4.0.3",
+    "@types/ember__object": "^4.0.5",
+    "@types/ember__polyfills": "^4.0.1",
+    "@types/ember__routing": "^4.0.12",
+    "@types/ember__runloop": "^4.0.2",
+    "@types/ember__service": "^4.0.1",
+    "@types/ember__string": "^3.0.10",
+    "@types/ember__test-helpers": "^2.8.2",
+    "@types/ember__utils": "^4.0.2",
     "algoliasearch": "^3.32.1",
     "babel-eslint": "^10.1.0",
     "bourbon": "5.1.0",
@@ -114,7 +132,8 @@
     "sass": "^1.54.4",
     "semver-compare": "^1.0.0",
     "spawndamnit": "2.0.0",
-    "testem": "^2.14.0"
+    "testem": "^2.14.0",
+    "typescript": "^4.9.3"
   },
   "engines": {
     "node": "14.* || 16.* || 18.*",
diff --git a/yarn.lock b/yarn.lock

-Original file line number
+Diff line change
@@ @@ -1,3 +1,5 @@ @@
 +<div>
 {{yield (hash
   sections=this.sections)
 }}
 +</div>