{"id":15640032,"url":"https://github.com/tylerturdenpants/ember-attacher","last_synced_at":"2025-05-16T06:07:12.832Z","repository":{"id":39545599,"uuid":"88448056","full_name":"tylerturdenpants/ember-attacher","owner":"tylerturdenpants","description":"Native tooltips and popovers for Ember.js","archived":false,"fork":false,"pushed_at":"2025-03-12T10:50:21.000Z","size":6547,"stargazers_count":82,"open_issues_count":18,"forks_count":44,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-10T02:51:58.186Z","etag":null,"topics":["addon","ember","ember-attacher","popovers","tooltips"],"latest_commit_sha":null,"homepage":"https://tylerturdenpants.github.io/ember-attacher/","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/tylerturdenpants.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2017-04-16T23:08:56.000Z","updated_at":"2025-01-09T07:47:01.000Z","dependencies_parsed_at":"2023-09-26T17:31:41.585Z","dependency_job_id":"4859800c-af13-456d-ab18-c30aa8489340","html_url":"https://github.com/tylerturdenpants/ember-attacher","commit_stats":{"total_commits":556,"total_committers":24,"mean_commits":"23.166666666666668","dds":0.6654676258992807,"last_synced_commit":"6def1bbebeb71656bab49e43159a5cf3266f170f"},"previous_names":["kybishop/ember-attacher"],"tags_count":65,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tylerturdenpants%2Fember-attacher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tylerturdenpants%2Fember-attacher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tylerturdenpants%2Fember-attacher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tylerturdenpants%2Fember-attacher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tylerturdenpants","download_url":"https://codeload.github.com/tylerturdenpants/ember-attacher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478190,"owners_count":22077676,"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":["addon","ember","ember-attacher","popovers","tooltips"],"created_at":"2024-10-03T11:30:16.800Z","updated_at":"2025-05-16T06:07:07.822Z","avatar_url":"https://github.com/tylerturdenpants.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ember-attacher\n\n[![npm version](https://badge.fury.io/js/ember-attacher.svg)](http://badge.fury.io/js/ember-attacher)\n[![Download count all time](https://img.shields.io/npm/dt/ember-attacher.svg)](https://www.npmjs.com/package/ember-attacher)\n[![npm](https://img.shields.io/npm/dm/ember-attacher.svg)](https://www.npmjs.com/package/ember-attacher)\n[![Ember Observer Score](http://emberobserver.com/badges/ember-attacher.svg)](http://emberobserver.com/addons/ember-attacher)\n[![GitHub CI](https://github.com/tylerturdenpants/ember-attacher/actions/workflows/ci.yml/badge.svg)](https://github.com/tylerturdenpants/ember-attacher/actions/workflows/ci.yml)\n\n## Compatibility\n\n------------------------------------------------------------------------------\n\n***NOTE***\n\n  The addon's dummy application needs a serious upgrade.  I [@tylerturdenpants](https://github.com/tylerturdenpants) have removed as much orf the support on flexi and flexi styles that I can, but the dummy app will still produces warnings regarding SASS division.\n\n  As the only supporter of this addon, a father, and a full time employee at a software company, I really need the help to fully pull flexi out and to revamp the dummy app.  Once these blockers are removed I can do the work to bring this addon into the future.\n\n----\n\n* Ember.js v3.20 through v5.12\n* Ember CLI v3.13 or above\n* Node.js v12 or above\n\nTooltips and popovers made easy.\nJust drop an `\u003cAttachTooltip/\u003e` or `\u003cAttachPopover/\u003e` in a parent and your floating element is ready to go!\n\n```hbs\n\u003cbutton\u003e\n  Click me\n\n  \u003cAttachTooltip\u003e\n    I'm a tooltip!\n  \u003c/AttachTooltip\u003e\n\u003c/button\u003e\n\n\u003cbutton class=\"other-button\"\u003e\n  No click me!\n\n  \u003cAttachPopover \n      @class='ember-attacher'\n      @hideOn='click'\n      @isShown={{true}}\n      @showOn='click'\n  \u003e\n    I'm a popover!\n  \u003c/AttachPopover\u003e\n\u003c/button\u003e\n```\n\nSee [the example site](https://tylerturdenpants.github.io/ember-attacher/) for a demonstration of all\navailable options.\n\n## Installation\n\n```bash\nember install ember-attacher\n```\n\nIf you're upgrading from 1.x to 2.x [see the upgrade guide](./docs/upgrade-guide-2.0.md).\n\n\n## Components\n\n### `\u003cAttachPopover/\u003e`\n\nA popover attacher.\n\n* Has no default class or roles.\n* Does not modify the target in any way.\n* Adds `aria-hidden` attribute to the floating element\n\n### `\u003cAttachTooltip/\u003e`\n\nA tooltip attacher. Subclass of `\u003cAttachPopover/\u003e`\n\n* Has the default class `'ember-attacher-floating ember-attacher-tooltip'`\n  * The default tooltip classes can be modified by altering the `tooltipClass`\n    default. See [here](#user-defined-defaults) for details on editing default values.\n\n* Default `role` attribute of `tooltip`.\n* Causes the target to gain an `aria-describedby` attribute set to the tooltip's ID.\n\n## Options\n\nBelow is a list of all available options, along with their defaults.\n\n```javascript\n{\n  // The animation used to present the animation.\n  // Options: ['fade', 'fill', 'none', 'perspective', 'scale', 'shift']\n  animation: 'fill',\n\n  // Whether or not an arrow will be displayed next to the attachment.\n  arrow: false,\n    \n  // Add listeners that will automatically call an update function\n  // Pass `true` to use the Floating UI default options or Options object to override them\n  // Example: { ancestorScroll: false }\n  // For more details see https://floating-ui.com/docs/autoUpdate \n  autoUpdate: false,\n\n  // A class that will be applied to the attachment.\n  class: null,\n\n  // The flip priority of the attacment.\n  // Space-delimited string, any combination of ['left', 'right', 'top', 'bottom']\n  //\n  // Example: 'left top bottom'\n  flip: null,\n\n  // The delay, in milliseconds, before the attachment will be hidden.\n  hideDelay: 0,\n\n  // The duration, in milliseconds, of the hide animation.\n  hideDuration: 300,\n\n  // Events that will cause the attachment to hide, typically in reference to the target.\n  //\n  // Space-delimited string, any combination of:\n  // ['click', 'clickout', 'mouseleave blur escapekey']\n  hideOn: 'mouseleave blur escapekey',\n\n  // Interactive tooltips will not close when clicked or hovered over.\n  interactive: false,\n\n  // Set this to true if you have an interactive attachment that hides on mouseout and the\n  // attachment is offset from its target. This should only be the case if you are using custom\n  // CSS that offsets that attachment.\n  isOffset: false,\n\n  // Whether or not the attachment is initially shown.\n  isShown: false,\n\n  // If true, the attachment will only be inserted into the DOM on the first \"show\" trigger.\n  // Useful for performance reasons, but will hide your attachment from search engines.\n  lazyRender: false,\n\n  // A middleware array that will be merged into computePosition options\n  middleware: null,\n\n  // A function to be fired when the attachment's visibility changes. The new visibility is passed\n  // to the function as an arg.\n  onChange: null,\n\n  // The initial position of the attachment.\n  // Options: ['left', 'right', 'top', 'bottom']\n  placement: 'top',\n\n  // The container where the attachment's DOM will be inserted.\n  floatingElementContainer: '.ember-application',\n\n  // An options object that will be passed to Floating UI \"computePosition\" function.\n  floatingUiOptions: null,\n\n  // NOT RECOMMENDED: We currently allow you to pass an explicit target, but this may be removed\n  // in a future release.\n  // Please provide your thoughts here: https://github.com/kybishop/ember-attacher/issues/109\n  explicitTarget: null,\n\n  // Whether or not to render the attachment in place in the DOM, as opposed to\n  // on the floatingElementContainer. NOTE: Rendering in place can cause z-index issues.\n  renderInPlace: false,\n\n  // The delay, in milliseconds, before the attachment will be shown.\n  showDelay: 0,\n\n  // The duration, in milliseconds, of the show animation.\n  showDuration: 300,\n\n  // Events on the target that will cause the attachment to show. For performance reasons, we\n  // recommend using some combination of 'mouseenter', 'focus', and 'click'\n  showOn: 'mouseenter focus',\n\n  // Whether to add event listeners for attachment show and hide in the capturing phase rather\n  // than the bubbling phase. This should be set to true when there are elements on the page that\n  // are stopping event propagation in the bubbling phase, and as a result preventing correct\n  // showing and hiding of popovers and tooltips.\n  useCapture: false,\n\n  // The default padding if collision happens. Set \"false\" if no collision prevention needed \n  overflowPadding: 5 \n}\n```\n\n## User-defined defaults\n\nUser-defined defaults can be set in the consuming app or addon's config/environment.js. These defaults will be applied to every `\u003cAttachPopover/\u003e` and `\u003cAttachTooltip/\u003e`\n\n```javascript\n// config/environment.js\n\nmodule.exports = function(environment) {\n  var ENV = {\n    emberAttacher: {\n      animation: 'shift',\n      arrow: true\n    }\n  };\n}\n```\n\nYou can also set the user-defined defaults separately like so:\n\n```javascript\n// config/environment.js\n\nmodule.exports = function(environment) {\n  var ENV = {\n    emberAttacher: {\n      tooltip: {\n        animation: 'fade',\n        arrow: true\n      },\n      popover: {\n        animation: 'shift',\n        arrow: false\n      }\n    }\n  };\n}\n```\n\nAnd finally you can do shared defaults along with user-defined separated defaults:\n\n```javascript\n// config/environment.js\n\nmodule.exports = function(environment) {\n  var ENV = {\n    emberAttacher: {\n      showDuration: 300,\n      hideDuration: 300,\n      tooltip: {\n        animation: 'fade',\n        arrow: true\n      },\n      popover: {\n        animation: 'shift',\n        arrow: false\n      }\n    }\n  };\n}\n```\n\nThe full list of editable defaults can be seen [here](https://github.com/kybishop/ember-attacher/blob/master/addon/defaults.js).\n\n## Styles\n\n`ember-attacher` provides [styles](https://github.com/kybishop/ember-attacher/blob/master/addon/styles/addon.scss#L85) for the default tooltip class, `ember-attacher-tooltip`, but no styles are included for `{{attach-popover}}`.\n\nExample styling for a popover [can be found in the dummy app](https://github.com/kybishop/ember-attacher/blob/master/tests/dummy/app/styles/app.scss#L132). Note how the arrow must also be styled to match the popover (background color, size, etc.)\n\n## Testing\n\nUse the `isVisible()` test helper to check if an attachment is visible.\n\n```javascript\nimport { click, find } from 'ember-native-dom-helpers';\nimport { isVisible } from 'ember-attacher';\n\ntest('example', async function(assert) {\n  this.render(hbs`\n    \u003cbutton id=\"toggle\"\u003e\n      Click me, captain!\n\n      \u003cAttachPopover \n          @id='attachment'\n          @hideOn='click'\n          @showOn='click'\n      \u003e\n        Click-toggled popover\n      \u003cAttachPopover/\u003e\n    \u003c/button\u003e\n  `);\n\n  const attachment = find('#attachment');\n\n  assert.equal(isVisible(attachment), false, 'Initially hidden');\n\n  await click('#toggle');\n\n  // You can also pass in a selector\n  assert.equal(isVisible('#attachment'), true, 'Now shown');\n});\n```\n\n## Development setup\n\nSee the [Contributing](CONTRIBUTING.md) guide for details.\n\n## FAQ\n\n### How animations are implemented\n\nAttachments are composed of two containers:\n\n* [An outer container](https://github.com/kybishop/ember-attacher/blob/master/addon/templates/components/attach-popover.hbs#L2) for positioning (via [floating-ui](https://github.com/floating-ui/floating-ui)).\n* [An inner container](https://github.com/kybishop/ember-attacher/blob/master/addon/templates/components/attach-popover.hbs#L12) for the content. This is the container that is animated.\n\nThe outer container is positioned right next to the target via the CSS `transform` property. The inner container is required because animations also use `transform`, which would otherwise conflict with the container's position.\n\n`transform` and `tansition-duration` are the CSS magic that allows animations to smoothly shift up/down, left/right, etc.\n\nNote that animations require an implementation for each position (left, right, top, and bottom):\n\n* \u003chttps://github.com/kybishop/ember-attacher/blob/master/addon/styles/addon.scss#L67\u003e\n\n* \u003chttps://github.com/kybishop/ember-attacher/blob/master/addon/styles/_mixins.scss#L75\u003e\n\n## Credits\n\n* [tippy.js](https://github.com/atomiks/tippyjs), the library that inspired\n  ember-attacher.\n\n* [floating-ui](https://github.com/floating-ui/floating-ui), the library that powers\n  positioning\n\n* [ember-tooltips](https://github.com/sir-dunxalot/ember-tooltips), the addon that\n  influenced much of ember-attacher's API.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftylerturdenpants%2Fember-attacher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftylerturdenpants%2Fember-attacher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftylerturdenpants%2Fember-attacher/lists"}