Add glint support

.gitignore

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

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,47 @@ 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!
+
+## 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 }],

ember-element-helper/package.json

@@ -11,19 +11,27 @@
     "dynamic element"
   ],
   "exports": {
-    ".": "./dist/index.js",
-    "./*": "./dist/*"
+    ".": {
+      "types": "./declarations/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./declarations/*.d.ts",
+      "default": "./dist/*"
+    },
+    "./addon-main.js": "./addon-main.cjs"
   },
   "files": [
     "dist",
+    "declarations",
     "addon-main.cjs",
     "CHANGELOG.md",
     "README.md"
   ],
   "scripts": {
     "start": "concurrently 'npm:watch:*'",
     "build": "concurrently 'npm:build:*'",
-    "build:js": "rollup -c ./rollup.config.js",
+    "build:js": "rollup -c",
     "build:docs": "cp ../README.md ./README.md",
     "watch:js": "rollup -c --watch --no-watch.clearScreen",
     "lint": "concurrently 'npm:lint:js'",
@@ -44,9 +52,18 @@
     "@babel/plugin-proposal-class-properties": "7.18.6",
     "@babel/plugin-syntax-decorators": "7.18.6",
     "@babel/plugin-proposal-decorators": "7.18.6",
-    "@embroider/addon-dev": "1.8.3",
+    "@babel/preset-typescript": "7.22.5",
+    "@babel/runtime": "^7.22.6",
+    "@embroider/addon-dev": "4.1.0",
     "@nullvoxpopuli/eslint-configs": "2.2.36",
+    "@rollup/plugin-babel": "6.0.3",
+    "@rollup/plugin-node-resolve": "15.1.0",
+    "@tsconfig/ember": "^3.0.0",
+    "@types/rsvp": "^4.0.4",
+    "@typescript-eslint/eslint-plugin": "^5.62.0",
+    "@typescript-eslint/parser": "^5.62.0",
     "concurrently": "7.2.2",
+    "ember-source": "~4.12.3",
     "eslint-config-prettier": "8.5.0",
     "eslint-plugin-decorator-position": "5.0.0",
     "eslint-plugin-ember": "10.6.1",
@@ -55,10 +72,10 @@
     "eslint-plugin-node": "11.1.0",
     "eslint-plugin-prettier": "4.2.1",
     "eslint-plugin-simple-import-sort": "7.0.0",
-    "rollup": "2.77.0",
+    "rollup": "3.26.3",
     "babel-eslint": "10.1.0",
     "eslint": "^7.31.0",
-    "@rollup/plugin-babel": "5.3.1"
+    "typescript": "5.1.6"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"

ember-element-helper/rollup.config.js → ember-element-helper/rollup.config.mjs

@@ -1,32 +1,31 @@
-import babel from '@rollup/plugin-babel';
+import { babel } from '@rollup/plugin-babel';
 import { Addon } from '@embroider/addon-dev/rollup';
+import { defineConfig } from 'rollup';
+import { nodeResolve } from '@rollup/plugin-node-resolve';
 
 const addon = new Addon({
   srcDir: 'src',
   destDir: 'dist',
 });
 
-export default {
+const extensions = ['.js', '.ts'];
+
+export default defineConfig({
   // This provides defaults that work well alongside `publicEntrypoints` below.
   // You can augment this if you need to.
   output: addon.output(),
 
   plugins: [
     // These are the modules that users should be able to import from your
     // addon. Anything not listed here may get optimized away.
-    addon.publicEntrypoints(['**/*.js']),
+    addon.publicEntrypoints(['index.js', 'helpers/element.js']),
 
     // These are the modules that should get reexported into the traditional
     // "app" tree. Things in here should also be in publicEntrypoints above, but
     // not everything in publicEntrypoints necessarily needs to go here.
-    addon.appReexports([
-      'components/**/*.js',
-      'helpers/**/*.js',
-      'modifiers/**/*.js',
-      'services/**/*.js',
-      'initializers/**/*.js',
-      'instance-initializers/**/*.js',
-    ]),
+    addon.appReexports(['helpers/element.js']),
+
+    nodeResolve({ extensions }),
 
     // This babel config should *not* apply presets or compile away ES modules.
     // It exists only to provide development niceties for you, like automatic
@@ -35,6 +34,7 @@ export default {
     // By default, this will load the actual babel config from the file
     // babel.config.json.
     babel({
+      extensions,
       babelHelpers: 'bundled',
     }),
 
@@ -53,4 +53,4 @@ export default {
     // Remove leftover build artifacts when starting a new build.
     addon.clean(),
   ],
-};
+});