{"id":13806894,"url":"https://github.com/tildeio/ember-element-helper","last_synced_at":"2025-04-07T17:11:50.404Z","repository":{"id":33154156,"uuid":"153330561","full_name":"tildeio/ember-element-helper","owner":"tildeio","description":"Dynamic element helper for Glimmer templates.","archived":false,"fork":false,"pushed_at":"2024-03-18T18:20:10.000Z","size":1865,"stargazers_count":44,"open_issues_count":20,"forks_count":23,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-31T14:13:11.034Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tildeio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-16T17:58:43.000Z","updated_at":"2024-06-11T16:04:47.000Z","dependencies_parsed_at":"2024-01-09T05:05:38.061Z","dependency_job_id":"a925fe04-81ac-47ac-a73d-2e2a1aff572b","html_url":"https://github.com/tildeio/ember-element-helper","commit_stats":{"total_commits":177,"total_committers":22,"mean_commits":8.045454545454545,"dds":0.8192090395480226,"last_synced_commit":"e72d56a58dfbe3af76c454ee180733840912d6cb"},"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tildeio%2Fember-element-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tildeio%2Fember-element-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tildeio%2Fember-element-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tildeio%2Fember-element-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tildeio","download_url":"https://codeload.github.com/tildeio/ember-element-helper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247694877,"owners_count":20980733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T01:01:17.644Z","updated_at":"2025-04-07T17:11:50.370Z","avatar_url":"https://github.com/tildeio.png","language":"JavaScript","funding_links":[],"categories":["Packages"],"sub_categories":["Helpers"],"readme":"# ember-element-helper\n\n[![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)\n\nDynamic element helper for Glimmer templates.\n\nThis addon provides a ~~polyfill~~ high fidelity reference implementation of\n[RFC #389](https://github.com/emberjs/rfcs/pull/389), including the proposed\namendments in [RFC PR #620](https://github.com/emberjs/rfcs/pull/620).\n\nPlease note that while [RFC #389](https://github.com/emberjs/rfcs/pull/389)\nhas been approved, it has not been implemented in Ember.js yet. As such, the\nfeature is still subject to change based on implementation feedback.\n\nWhen this feature is implemented in Ember.js, we will release a 1.0 version of\nthis addon as a true polyfill for the feature, allowing the feature to be used\non older Ember.js versions and be completely inert on newer versions where the\nofficial implementation is available.\n\n## Compatibility\n\n* Ember.js v3.28 or above\n* Ember CLI v3.28 or above\n* Node.js v12 or above\n\n## Limitations\n\nThis implementation has the following known limitations:\n\n* By default, an auto-generated `id` attribute will be added to the element\n  (e.g. `id=\"ember123\"`). It is possible to override this by providing an\n  `id` attribute when invoking the component (e.g. `\u003cTag id=\"my-id\" /\u003e`).\n  However, it is not possible to remove the `id` attribute completely. The\n  proposed helper will not have this behavior, as such this should not be\n  relied upon (e.g. in CSS and `qunit-dom` selectors).\n\n* The element will have an `ember-view` class (i.e. `class=\"ember-view\"`).\n  This is in addition and merged with the class attribute provided when\n  invoking the component (e.g. `\u003cTag class=\"my-class\" /\u003e` will result in\n  something like `\u003cdiv class=\"ember-view my-class\" /\u003e`). It is not possible\n  to remove the `ember-view` class. The proposed helper will not have this\n  behavior, as such this should not be relied upon (e.g. in CSS and `qunit-dom`\n  selectors).\n\n* In Ember versions before 3.11, modifiers cannot be passed to the element,\n  even when addons such as the [modifier manager](https://github.com/ember-polyfills/ember-modifier-manager-polyfill)\n  and [on modifier](https://github.com/buschtoens/ember-on-modifier) polyfills\n  are used. Doing so requires [RFC #435](https://github.com/emberjs/rfcs/blob/master/text/0435-modifier-splattributes.md)\n  which is first available on Ember 3.11. This is an Ember.js limitation,\n  unrelated to this addon.\n\n## Installation\n\n```\nember install ember-element-helper\n```\n\n## Usage\n\n```hbs\n{{#let (element this.tagName) as |Tag|}}\n  \u003cTag class=\"my-tag\"\u003ehello world!\u003c/Tag\u003e\n{{/let}}\n```\n\nYou can also pass around the result of invoking this helper into any components\nthat accepts \"contextual components\" as arguments:\n\n```hbs\n\u003cMyComponent @tag={{element \"span\"}} /\u003e\n```\n\n```hbs\n{{!-- in my-component.hbs --}}\n{{#let @tag as |Tag|}}\n  \u003cTag class=\"my-tag\"\u003ehello world!\u003c/Tag\u003e\n{{/let}}\n\n{{!-- ...or more directly... --}}\n\u003c@tag class=\"my-tag\"\u003ehello world!\u003c/@tag\u003e\n```\n\n### Single File Components\n\nUsing the `(element)` helper with [first class component\ntemplates](http://emberjs.github.io/rfcs/0779-first-class-component-templates.html):\n\n```gjs\nimport { element } from 'ember-element-helper';\n\n\u003ctemplate\u003e\n  {{#let (element @tagName) as |Tag|}}\n    \u003cTag class=\"my-tag\"\u003ehello world!\u003c/Tag\u003e\n  {{/let}}\n\u003c/template\u003e\n```\n\n### Glint Usage in Classic Mode\n\nIn order to use a typed `(element)` helper in classic mode, you need to import\nthe addon's glint template registry and extend your app's registry declaration\nas described in the [Using\nAddons](https://typed-ember.gitbook.io/glint/using-glint/ember/using-addons#using-glint-enabled-addons)\ndocumentation:\n\n```ts\nimport '@glint/environment-ember-loose';\nimport type EmberElementHelperRegistry from 'ember-element-helper/template-registry';\n\ndeclare module '@glint/environment-ember-loose/registry' {\n  export default interface Registry extends EmberElementHelperRegistry, /* other addon registries */ {\n    // local entries\n  }\n}\n```\n\n\u003e **Note:** Glint itself is still under active development, and as such breaking changes might occur.\n\u003e Therefore, Glint support by this addon is also considered experimental, and not covered by our SemVer contract!\n\n### Typing your Components\n\nWhen your component accepts an element with the `(element)` helper, you want to\ngive this argument a proper type. Here is how:\n\n```ts\nimport type { ElementSignature } from 'ember-element-helper';\n\ninterface YourComponentSignature\u003cT extends string\u003e {\n  Element: HTMLSectionElement;\n  Args: {\n    element?: ElementSignature['Return'];\n  };\n}\n```\n\nWhen the `@element` argument influences the `Element` of your component:\n\n```ts\nimport type { ElementSignature, ElementFromTagName } from 'ember-element-helper';\n\ninterface YourComponentSignature\u003cT extends string\u003e {\n  Element: ElementFromTagName\u003cT\u003e;\n  Args: {\n    element?: ElementSignature\u003cT\u003e['Return'];\n  };\n}\n```\n\nWhen your component already uses an element for a given condition. When\nthe condition isn't met, a fallback element is used. The fallback can even be\nprovided from the outside. Here is the type:\n\n```ts\nimport type { ElementSignature, ElementFromTagName } from 'ember-element-helper';\n\ninterface YourComponentSignature\u003c\n  T extends string = 'section'\n\u003e {\n  Element: HTMLButtonElement | HTMLAnchorElement | ElementFromTagName\u003cT\u003e;\n  Args: {\n    element?: ElementSignature\u003cT\u003e['Return'];\n  };\n}\n```\n\n## Contributing\n\nSee the [Contributing](CONTRIBUTING.md) guide for details.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftildeio%2Fember-element-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftildeio%2Fember-element-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftildeio%2Fember-element-helper/lists"}