Merge pull request #107 from gossi/glint-support

Add glint support

.github/workflows/ci.yml

@@ -52,7 +52,6 @@ jobs:
       fail-fast: false
       matrix:
         try-scenario:
-          - ember-lts-3.24
           - ember-lts-3.28
           - ember-lts-4.4
           - ember-lts-4.8
@@ -72,6 +71,33 @@ jobs:
         run: pnpm exec ember try:one ${{ matrix.try-scenario }} --skip-cleanup
         working-directory: test-app
 
+  typecheck:
+    name: "${{ matrix.typescript-scenario }}"
+    runs-on: ubuntu-latest
+    needs: "test"
+    timeout-minutes: 5
+    continue-on-error: true
+    strategy:
+      fail-fast: true
+      matrix:
+        typescript-scenario:
+          - [email protected]
+          - [email protected]
+          - [email protected]
+          - [email protected]
+
+    steps:
+      - name: Setup
+        uses: wyvox/action@v1
+      - name: "Change TS to ${{ matrix.typescript-scenario }}"
+        run: "pnpm add --save-dev ${{ matrix.typescript-scenario}}"
+        working-directory: ./test-app
+      - name: "Type checking"
+        run: |
+          pnpm --filter "test-app*" exec tsc -v;
+          pnpm --filter "test-app*" exec glint --version;
+          pnpm --filter "test-app*" exec glint;
+
   publish:
     name: Publish
     needs: test

.gitignore

@@ -2,6 +2,7 @@
 
 # compiled output
 dist/
+declarations/
 tmp/
 
 # dependencies

.npmrc

@@ -1,5 +1,6 @@
 public-hoist-pattern[]=*prettier*
 public-hoist-pattern[]=*eslint*
-public-hoist-pattern[]=!@typescript-eslint/*
+public-hoist-pattern[]=@typescript-eslint/*
 public-hoist-pattern[]=*ember-template-lint*
 public-hoist-pattern[]=*stylelint*
+public-hoist-pattern[]=*@glint*

README.md

@@ -1,5 +1,4 @@
-ember-element-helper
-==============================================================================
+# ember-element-helper
 
 [![Build Status](https://github.com/tildeio/ember-element-helper/actions/workflows/ci.yml/badge.svg)](https://github.com/tildeio/ember-element-helper/actions/workflows/ci.yml)
 
@@ -18,15 +17,13 @@ this addon as a true polyfill for the feature, allowing the feature to be used
 on older Ember.js versions and be completely inert on newer versions where the
 official implementation is available.
 
-Compatibility
-------------------------------------------------------------------------------
+## Compatibility
 
 * Ember.js v3.24 or above
 * Ember CLI v3.24 or above
 * Node.js v12 or above
 
-Limitations
-------------------------------------------------------------------------------
+## Limitations
 
 This implementation has the following known limitations:
 
@@ -52,15 +49,13 @@ This implementation has the following known limitations:
   which is first available on Ember 3.11. This is an Ember.js limitation,
   unrelated to this addon.
 
-Installation
-------------------------------------------------------------------------------
+## Installation
 
 ```
 ember install ember-element-helper
 ```
 
-Usage
-------------------------------------------------------------------------------
+## Usage
 
 ```hbs
 {{#let (element this.tagName) as |Tag|}}
@@ -85,12 +80,93 @@ that accepts "contextual components" as arguments:
 <@tag class="my-tag">hello world!</@tag>
 ```
 
-Contributing
-------------------------------------------------------------------------------
+### Single File Components
+
+Using the `(element)` helper with [first class component
+templates](http://emberjs.github.io/rfcs/0779-first-class-component-templates.html):
+
+```gjs
+import { element } from 'ember-element-helper';
+
+<template>
+  {{#let (element @tagName) as |Tag|}}
+    <Tag class="my-tag">hello world!</Tag>
+  {{/let}}
+</template>
+```
+
+### Glint Usage in Classic Mode
+
+In order to use a typed `(element)` helper in classic mode, you need to import
+the addon's glint template registry and extend your app's registry declaration
+as described in the [Using
+Addons](https://typed-ember.gitbook.io/glint/using-glint/ember/using-addons#using-glint-enabled-addons)
+documentation:
+
+```ts
+import '@glint/environment-ember-loose';
+import type EmberElementHelperRegistry from 'ember-element-helper/template-registry';
+
+declare module '@glint/environment-ember-loose/registry' {
+  export default interface Registry extends EmberElementHelperRegistry, /* other addon registries */ {
+    // local entries
+  }
+}
+```
+
+> **Note:** Glint itself is still under active development, and as such breaking changes might occur.
+> Therefore, Glint support by this addon is also considered experimental, and not covered by our SemVer contract!
+
+### Typing your Components
+
+When your component accepts an element with the `(element)` helper, you want to
+give this argument a proper type. Here is how:
+
+```ts
+import type { ElementSignature } from 'ember-element-helper';
+
+interface YourComponentSignature<T extends string> {
+  Element: HTMLSectionElement;
+  Args: {
+    element?: ElementSignature['Return'];
+  };
+}
+```
+
+When the `@element` argument influences the `Element` of your component:
+
+```ts
+import type { ElementSignature, ElementFromTagName } from 'ember-element-helper';
+
+interface YourComponentSignature<T extends string> {
+  Element: ElementFromTagName<T>;
+  Args: {
+    element?: ElementSignature<T>['Return'];
+  };
+}
+```
+
+When your component already uses an element for a given condition. When
+the condition isn't met, a fallback element is used. The fallback can even be
+provided from the outside. Here is the type:
+
+```ts
+import type { ElementSignature, ElementFromTagName } from 'ember-element-helper';
+
+interface YourComponentSignature<
+  T extends string = 'section'
+> {
+  Element: HTMLButtonElement | HTMLAnchorElement | ElementFromTagName<T>;
+  Args: {
+    element?: ElementSignature<T>['Return'];
+  };
+}
+```
+
+## Contributing
 
 See the [Contributing](CONTRIBUTING.md) guide for details.
 
-License
-------------------------------------------------------------------------------
+## License
 
 This project is licensed under the [MIT License](LICENSE.md).

ember-element-helper/README.md

@@ -1,5 +1,4 @@
-ember-element-helper
-==============================================================================
+# ember-element-helper
 
 [![Build Status](https://github.com/tildeio/ember-element-helper/actions/workflows/ci.yml/badge.svg)](https://github.com/tildeio/ember-element-helper/actions/workflows/ci.yml)
 
@@ -18,15 +17,13 @@ this addon as a true polyfill for the feature, allowing the feature to be used
 on older Ember.js versions and be completely inert on newer versions where the
 official implementation is available.
 
-Compatibility
-------------------------------------------------------------------------------
+## Compatibility
 
 * Ember.js v3.24 or above
 * Ember CLI v3.24 or above
 * Node.js v12 or above
 
-Limitations
-------------------------------------------------------------------------------
+## Limitations
 
 This implementation has the following known limitations:
 
@@ -52,15 +49,13 @@ This implementation has the following known limitations:
   which is first available on Ember 3.11. This is an Ember.js limitation,
   unrelated to this addon.
 
-Installation
-------------------------------------------------------------------------------
+## Installation
 
 ```
 ember install ember-element-helper
 ```
 
-Usage
-------------------------------------------------------------------------------
+## Usage
 
 ```hbs
 {{#let (element this.tagName) as |Tag|}}
@@ -85,12 +80,93 @@ that accepts "contextual components" as arguments:
 <@tag class="my-tag">hello world!</@tag>
 ```
 
-Contributing
-------------------------------------------------------------------------------
+### Single File Components
+
+Using the `(element)` helper with [first class component
+templates](http://emberjs.github.io/rfcs/0779-first-class-component-templates.html):
+
+```gjs
+import { element } from 'ember-element-helper';
+
+<template>
+  {{#let (element @tagName) as |Tag|}}
+    <Tag class="my-tag">hello world!</Tag>
+  {{/let}}
+</template>
+```
+
+### Glint Usage in Classic Mode
+
+In order to use a typed `(element)` helper in classic mode, you need to import
+the addon's glint template registry and extend your app's registry declaration
+as described in the [Using
+Addons](https://typed-ember.gitbook.io/glint/using-glint/ember/using-addons#using-glint-enabled-addons)
+documentation:
+
+```ts
+import '@glint/environment-ember-loose';
+import type EmberElementHelperRegistry from 'ember-element-helper/template-registry';
+
+declare module '@glint/environment-ember-loose/registry' {
+  export default interface Registry extends EmberElementHelperRegistry, /* other addon registries */ {
+    // local entries
+  }
+}
+```
+
+> **Note:** Glint itself is still under active development, and as such breaking changes might occur.
+> Therefore, Glint support by this addon is also considered experimental, and not covered by our SemVer contract!
+
+### Typing your Components
+
+When your component accepts an element with the `(element)` helper, you want to
+give this argument a proper type. Here is how:
+
+```ts
+import type { ElementSignature } from 'ember-element-helper';
+
+interface YourComponentSignature<T extends string> {
+  Element: HTMLSectionElement;
+  Args: {
+    element?: ElementSignature['Return'];
+  };
+}
+```
+
+When the `@element` argument influences the `Element` of your component:
+
+```ts
+import type { ElementSignature, ElementFromTagName } from 'ember-element-helper';
+
+interface YourComponentSignature<T extends string> {
+  Element: ElementFromTagName<T>;
+  Args: {
+    element?: ElementSignature<T>['Return'];
+  };
+}
+```
+
+When your component already uses an element for a given condition. When
+the condition isn't met, a fallback element is used. The fallback can even be
+provided from the outside. Here is the type:
+
+```ts
+import type { ElementSignature, ElementFromTagName } from 'ember-element-helper';
+
+interface YourComponentSignature<
+  T extends string = 'section'
+> {
+  Element: HTMLButtonElement | HTMLAnchorElement | ElementFromTagName<T>;
+  Args: {
+    element?: ElementSignature<T>['Return'];
+  };
+}
+```
+
+## Contributing
 
 See the [Contributing](CONTRIBUTING.md) guide for details.
 
-License
-------------------------------------------------------------------------------
+## License
 
 This project is licensed under the [MIT License](LICENSE.md).

ember-element-helper/babel.config.json

@@ -1,4 +1,5 @@
 {
+  "presets": ["@babel/preset-typescript"],
   "plugins": [
     "@embroider/addon-dev/template-colocation-plugin",
     ["@babel/plugin-proposal-decorators", { "legacy": true }],