{"id":15060331,"url":"https://github.com/crowdstrike/ember-velcro","last_synced_at":"2025-04-10T05:51:00.303Z","repository":{"id":40700857,"uuid":"423300804","full_name":"CrowdStrike/ember-velcro","owner":"CrowdStrike","description":"Ember Velcro sticks one element to another with Floating UI.","archived":false,"fork":false,"pushed_at":"2025-03-17T13:12:10.000Z","size":2151,"stargazers_count":13,"open_issues_count":19,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-21T10:53:40.860Z","etag":null,"topics":["emberjs","emberjs-addon","floating-ui","popperjs","positioning"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/CrowdStrike.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":"2021-11-01T01:21:54.000Z","updated_at":"2024-11-11T01:17:47.000Z","dependencies_parsed_at":"2024-01-01T02:29:42.051Z","dependency_job_id":"8c0ff819-941d-4350-a667-8d952fecf913","html_url":"https://github.com/CrowdStrike/ember-velcro","commit_stats":{"total_commits":107,"total_committers":5,"mean_commits":21.4,"dds":0.6448598130841121,"last_synced_commit":"8a8c941854f1cdddd9cb2cac2096fc59f75bf06c"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrowdStrike%2Fember-velcro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrowdStrike%2Fember-velcro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrowdStrike%2Fember-velcro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CrowdStrike%2Fember-velcro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CrowdStrike","download_url":"https://codeload.github.com/CrowdStrike/ember-velcro/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248166926,"owners_count":21058480,"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":["emberjs","emberjs-addon","floating-ui","popperjs","positioning"],"created_at":"2024-09-24T22:56:55.828Z","updated_at":"2025-04-10T05:51:00.277Z","avatar_url":"https://github.com/CrowdStrike.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Ember Velcro\n==============================================================================\n\nEmber Velcro sticks one element to another with [Floating UI](https://floating-ui.com/), it can be used as a modifier or a component.\n\nSeveral of Floating UI's functions and [middleware](https://floating-ui.com/docs/middleware) are used to create an experience out of the box that is useful and expected.\n\nSee Floating UI's [documentation](https://floating-ui.com/docs/getting-started) for more information on any of the following included functionality.\n\nFunctions:\n\n[computePosition](https://floating-ui.com/docs/computePosition) - computes the x and y coordinates needed to anchor a floating element to a reference element.\n\n[autoUpdate](https://floating-ui.com/docs/autoUpdate) - updates the x and y coordinates of the floating element so it remains anchored to the reference element when the page scrolls or when either the reference or floating elements are resized.\n\nMiddleware:\n\n[offset](https://floating-ui.com/docs/offset) - the first of the middleware included; allows you to offset the floating element from the reference element by a given amount.\n\n[flip](https://floating-ui.com/docs/flip) - flips the floating element to the opposite side of the reference element to keep it in view.\n\n[shift](https://floating-ui.com/docs/shift) - shifts the floating element along the x or y axis to keep it in view\n* x-axis for 'top' and 'bottom' placements\n* y-axis for 'left' and 'right' placements\n\n[hide](https://floating-ui.com/docs/hide) - hides the floating element when the reference element is no longer visible or when the floating element has escaped the reference element's clipping context.\n\n\nAPI\n------------------------------------------------------------------------------\n\n* `@flipOptions` - see [flip docs](https://floating-ui.com/docs/flip) for option values\n* `@middleware` - array of one or more objects to add to the [middleware](https://floating-ui.com/docs/middleware) array\n* `@offsetOptions` - see [offset docs](https://floating-ui.com/docs/offset) for option values\n* `@placement` - list of [expected values](https://floating-ui.com/docs/computeposition#placement)\n* `@shiftOptions` - see [shift docs](https://floating-ui.com/docs/shift) for option values\n* `@strategy` - CSS position property, either 'fixed' or 'absolute'. Pros and cons of each strategy is [here](https://floating-ui.com/docs/computePosition#strategy)\n\n\nDefault values\n------------------------------------------------------------------------------\n\n* `@placement`: 'bottom'\n* `@strategy`: 'fixed'\n* `offset`, `flip`, and `shift` middleware all use their defaults.\n* `hide` middleware uses both `referenceHidden` and `escaped` [options](https://floating-ui.com/docs/hide#options).\n\nUsage as Modifier\n------------------------------------------------------------------------------\n\n```hbs\n\u003cdiv id=\"hook\"\u003eThe `reference` element (the hook)\u003c/div\u003e\n\u003cdiv {{velcro \"#hook\"}}\u003eThe `floating` element (the loop)\u003c/div\u003e\n```\n\nUsage as Component\n------------------------------------------------------------------------------\n\nThe `Velcro` component yields a single hash - 2 modifiers and 'velcro data':\n\n```hbs\n\u003cVelcro as |velcro|\u003e\n  \u003cdiv {{velcro.hook}}\u003eVelcro hook\u003c/div\u003e\n  \u003cdiv {{velcro.loop}}\u003eVelcro loop stuck to Velcro hook!\u003c/div\u003e\n  {{log \"velcro data\" velcro.data}}\n\u003c/Velcro\u003e\n```\n\n`velcro.data` is the `MiddlewareArguments` object, it contains the following values:\n\n* x\n* y\n* initialPlacement\n* placement\n* strategy\n* middlewareData\n* rects\n* platform\n* elements\n\nSee [MiddlewareArguments](https://floating-ui.com/docs/middleware#middlewarearguments) for a description of each.\n\n\u003cdetails\u003e\n \u003csummary\u003eYou can also use `velcro.setHook` yielded function for more complex composibility scenarios. Expand to read more.\u003c/summary\u003e\n\n## `setHook`\n\nImagine you're writing a dropdown component with ember-velcro. You want to yield a `trigger` modifier that does two things:\n1. sets an element as the \"hook\" for ember-velcro\n2. attaches a click handler to toggle between the open/closed states\n\nWithout the yielded `setHook` function, this would not be possible. With `setHook` however, we can pass that function to the modifier, and the modifier can call that function with the element.\n\nSuch a dropdown component might look something like this:\n\n```gjs\nlet myModifier = modifier((element, [setHook, handler]) =\u003e {\n  // call ember-velcro's setHook\n  setHook(element);\n\n  // other custom logic\n  element.addEventListener('click', handler);\n\n  return () =\u003e {\n    element.removeEventListener('click', handler);\n  };\n});\n\n\u003ctemplate\u003e\n  \u003cVelcro as |velcro|\u003e\n    {{yield (hash\n      trigger=(modifier myModifier velcro.setHook onClick)\n    )}}\n  \u003c/Velcro\u003e\n\u003c/template\u003e\n```\n\nThis is needed because, at the time of writing, there's no way in ember to combine two existing modifiers into a single one. You can check the relevant [pull request](https://github.com/CrowdStrike/ember-velcro/pull/186) for more information.\n\n\n\u003c/details\u003e\n\nCompatibility\n------------------------------------------------------------------------------\n\n* Ember.js v3.20 or above\n* Ember CLI v3.20 or above\n* Node.js v14 or above\n\n\nInstallation\n------------------------------------------------------------------------------\n\n```\nnpm install ember-velcro\n# or\nyarn add ember-velcro\n# or\npnpm install ember-velcro\n# or\nember install ember-velcro\n```\n\nComparison to similar projects\n------------------------------------------------------------------------------\n\nSimilar projects include:\n\n* [ember-popperjs](https://github.com/NullVoxPopuli/ember-popperjs)\n* [ember-popper-modifier](https://github.com/adopted-ember-addons/ember-popper-modifier)\n\nThe above projects both use [Popper](https://popper.js.org/). In contrast, Ember Velcro uses Floating UI. Floating UI is the successor to Popper - see their [migration guide](https://floating-ui.com/docs/migration) for a complete comparison.\n\nLicense\n------------------------------------------------------------------------------\n\nThis project is licensed under the [MIT License](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrowdstrike%2Fember-velcro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrowdstrike%2Fember-velcro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrowdstrike%2Fember-velcro/lists"}