{"_id":"@a11y-ngx/overlay","_rev":"11-731de45af86ebaf27b67bfabaef82cd9","name":"@a11y-ngx/overlay","dist-tags":{"latest":"1.0.7"},"versions":{"1.0.1":{"name":"@a11y-ngx/overlay","version":"1.0.1","keywords":["overlay","position","positioning","reposition","viewport","boundary","overflow","component","directive","scroll","scrolling","resize","accessibility","angular"],"author":{"url":"https://github.com/LDV2k3/","name":"Luciano Del Vacchio","email":"lucho.development@gmail.com"},"license":"MPL-2.0","_id":"@a11y-ngx/overlay@1.0.1","maintainers":[{"name":"ldv","email":"lucho.development@gmail.com"}],"homepage":"https://github.com/LDV2k3/a11y-libraries/tree/master/projects/a11y-ngx/overlay#readme","bugs":{"url":"https://github.com/LDV2k3/a11y-libraries/issues","email":"lucho.development@gmail.com"},"dist":{"shasum":"0d1081c9edf4c0aa7a43e786aad473c0194b2aa1","tarball":"https://registry.npmjs.org/@a11y-ngx/overlay/-/overlay-1.0.1.tgz","fileCount":42,"integrity":"sha512-CPtC9wlgbMiRT4g1QIkrWOaiRn1sqBdgNZukDDvOdZzKpJRh2ZZ9h2e6e93K9U6cTyRY9n6uY99EC0266y+CkQ==","signatures":[{"sig":"MEUCIH9EnjPl01MNkEZ9vEs8C1WBqb8g5a/fa06INRqU8YgqAiEAvpPLwKlK237CSKKDykVFjKhvZ61b8xpPg61O6gk+sAQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":969610},"main":"bundles/a11y-ngx-overlay.umd.js","es2015":"fesm2015/a11y-ngx-overlay.js","module":"fesm2015/a11y-ngx-overlay.js","esm2015":"esm2015/a11y-ngx-overlay.js","gitHead":"0fd2f55da3c44b4039f1100b79a8a6edc126cbdf","typings":"a11y-ngx-overlay.d.ts","_npmUser":{"name":"ldv","email":"lucho.development@gmail.com"},"fesm2015":"fesm2015/a11y-ngx-overlay.js","_npmVersion":"8.19.4","description":"A floating overlay-style element that stays within the visible area of the viewport or a given custom boundary (like containers with overflow), preventing it from going off-screen during scroll or window resize","directories":{},"sideEffects":false,"_nodeVersion":"16.20.2","dependencies":{"tslib":"^1.10.0","@a11y-ngx/tab-cycle":">=1.0.1","@a11y-ngx/dom-helper":">=1.0.0","@a11y-ngx/color-scheme":">=1.0.6","@a11y-ngx/overlay-base":">=1.0.0"},"_hasShrinkwrap":false,"peerDependencies":{"@angular/core":"^12.2.0","@angular/common":"^12.2.0"},"_npmOperationalInternal":{"tmp":"tmp/overlay_1.0.1_1760049131558_0.6737173439376565","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@a11y-ngx/overlay","version":"1.0.2","keywords":["overlay","position","positioning","reposition","viewport","boundary","overflow","component","directive","scroll","scrolling","resize","accessibility","angular"],"author":{"url":"https://github.com/LDV2k3/","name":"Luciano Del Vacchio","email":"lucho.development@gmail.com"},"license":"MPL-2.0","_id":"@a11y-ngx/overlay@1.0.2","maintainers":[{"name":"ldv","email":"lucho.development@gmail.com"}],"homepage":"https://github.com/LDV2k3/a11y-libraries/tree/master/projects/a11y-ngx/overlay#readme","bugs":{"url":"https://github.com/LDV2k3/a11y-libraries/issues","email":"lucho.development@gmail.com"},"dist":{"shasum":"a078a013c8037a3de1a83a5613435b66b80dbb45","tarball":"https://registry.npmjs.org/@a11y-ngx/overlay/-/overlay-1.0.2.tgz","fileCount":42,"integrity":"sha512-rOtG4++vqu61deghKQBOEIh6sol2N00USWI7I7oKjKzL/kAnNh3+bbPx/QGQzdNacXcrbJSznQYw+Le7Z28ONA==","signatures":[{"sig":"MEQCIEZsg0hLpecJyJGCEUnAujqepTi//E6guhSFW1RNVzvDAiAji7uvf03idjaJCEw7DVvB3tgPCAwb0y8Z1rvZusdrLQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":969628},"main":"bundles/a11y-ngx-overlay.umd.js","es2015":"fesm2015/a11y-ngx-overlay.js","module":"fesm2015/a11y-ngx-overlay.js","esm2015":"esm2015/a11y-ngx-overlay.js","gitHead":"0943b42a1333a74cbda740380ef033e73c182dd5","typings":"a11y-ngx-overlay.d.ts","_npmUser":{"name":"ldv","email":"lucho.development@gmail.com"},"fesm2015":"fesm2015/a11y-ngx-overlay.js","deprecated":"this version has been deprecated","_npmVersion":"8.19.4","description":"A floating overlay-style element that stays within the visible area of the viewport or a given custom boundary (like containers with overflow), preventing it from going off-screen during scroll or window resize","directories":{},"sideEffects":false,"_nodeVersion":"16.20.2","dependencies":{"tslib":"^1.10.0","@a11y-ngx/tab-cycle":">=1.0.2","@a11y-ngx/dom-helper":">=1.1.1","@a11y-ngx/color-scheme":">=1.0.7","@a11y-ngx/overlay-base":">=1.0.1"},"_hasShrinkwrap":false,"peerDependencies":{"@angular/core":">=12.2.0 <21.0.0","@angular/common":">=12.2.0 <21.0.0"},"_npmOperationalInternal":{"tmp":"tmp/overlay_1.0.2_1761916407652_0.13354640365978687","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@a11y-ngx/overlay","version":"1.0.3","keywords":["overlay","position","positioning","reposition","viewport","boundary","overflow","component","directive","scroll","scrolling","resize","accessibility","angular"],"author":{"url":"https://github.com/LDV2k3/","name":"Luciano Del Vacchio","email":"lucho.development@gmail.com"},"license":"MPL-2.0","_id":"@a11y-ngx/overlay@1.0.3","maintainers":[{"name":"ldv","email":"lucho.development@gmail.com"}],"homepage":"https://github.com/LDV2k3/a11y-libraries/tree/master/projects/a11y-ngx/overlay#readme","bugs":{"url":"https://github.com/LDV2k3/a11y-libraries/issues","email":"lucho.development@gmail.com"},"dist":{"shasum":"e64807fb11ad1b4259e83df5b9d9a628454c38db","tarball":"https://registry.npmjs.org/@a11y-ngx/overlay/-/overlay-1.0.3.tgz","fileCount":44,"integrity":"sha512-ODGFqEWcz91KyetUk2/RTX3n6a2IdLKkxa6V9a7YCekAIrbkqhwf+Iq2gvp+Om/FKeGtA4wQ2UQHe+J94kFQpQ==","signatures":[{"sig":"MEUCIQDW1d7KmWtsxbbuOFmQSVFrOlsYg6D7X71L9UCCAS3s8wIgD+xDXUFd/ex24vTNaepRKXfRVNXvGj6AafNwGaYqbUg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":975150},"main":"bundles/a11y-ngx-overlay.umd.js","es2015":"fesm2015/a11y-ngx-overlay.js","module":"fesm2015/a11y-ngx-overlay.js","esm2015":"esm2015/a11y-ngx-overlay.js","gitHead":"0943b42a1333a74cbda740380ef033e73c182dd5","typings":"a11y-ngx-overlay.d.ts","_npmUser":{"name":"ldv","email":"lucho.development@gmail.com"},"fesm2015":"fesm2015/a11y-ngx-overlay.js","_npmVersion":"8.19.4","description":"A floating overlay-style element that stays within the visible area of the viewport or a given custom boundary (like containers with overflow), preventing it from going off-screen during scroll or window resize","directories":{},"sideEffects":false,"_nodeVersion":"16.20.2","dependencies":{"tslib":"^1.10.0","@a11y-ngx/tab-cycle":">=1.0.2","@a11y-ngx/dom-helper":">=1.1.1","@a11y-ngx/color-scheme":">=1.0.7","@a11y-ngx/overlay-base":">=1.0.1"},"_hasShrinkwrap":false,"peerDependencies":{"@angular/core":">=12.2.0 <21.0.0","@angular/common":">=12.2.0 <21.0.0"},"_npmOperationalInternal":{"tmp":"tmp/overlay_1.0.3_1761923377148_0.37756249882340875","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@a11y-ngx/overlay","version":"1.0.4","keywords":["overlay","position","positioning","reposition","viewport","boundary","overflow","component","directive","scroll","scrolling","resize","accessibility","angular"],"author":{"url":"https://github.com/LDV2k3/","name":"Luciano Del Vacchio","email":"lucho.development@gmail.com"},"license":"MPL-2.0","_id":"@a11y-ngx/overlay@1.0.4","maintainers":[{"name":"ldv","email":"lucho.development@gmail.com"}],"homepage":"https://github.com/LDV2k3/a11y-libraries/tree/master/projects/a11y-ngx/overlay#readme","bugs":{"url":"https://github.com/LDV2k3/a11y-libraries/issues","email":"lucho.development@gmail.com"},"dist":{"shasum":"fdd70bf77a3663d266a58e62185aa5d8c9be4620","tarball":"https://registry.npmjs.org/@a11y-ngx/overlay/-/overlay-1.0.4.tgz","fileCount":44,"integrity":"sha512-w7GlO6dxs/v6kRPiqnn3iPI3WTgQMciFLBHi77EMrMxGFI224uCRmNpjYl0cZvI03VwMgFiU9qnY8BHARtNRlA==","signatures":[{"sig":"MEUCIQC8tBbJDrLfUA8hNOAR0tyuo4Fzn8/Tm6CL244kR8DdzAIgXmeb5OV6Xc5Z/NMbXpjx2sXrE5wZ0xuVAjRwcdoyTFw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":975703},"main":"bundles/a11y-ngx-overlay.umd.js","es2015":"fesm2015/a11y-ngx-overlay.js","module":"fesm2015/a11y-ngx-overlay.js","esm2015":"esm2015/a11y-ngx-overlay.js","gitHead":"74738a99d8af404735edcf4f279f268825ca0c79","typings":"a11y-ngx-overlay.d.ts","_npmUser":{"name":"ldv","email":"lucho.development@gmail.com"},"fesm2015":"fesm2015/a11y-ngx-overlay.js","deprecated":"change detection issues","_npmVersion":"8.19.4","description":"A floating overlay-style element that stays within the visible area of the viewport or a given custom boundary (like containers with overflow), preventing it from going off-screen during scroll or window resize","directories":{},"sideEffects":false,"_nodeVersion":"16.20.2","dependencies":{"tslib":"^1.10.0","@a11y-ngx/tab-cycle":"^1.0.2","@a11y-ngx/dom-helper":"^1.1.1","@a11y-ngx/color-scheme":"^1.0.8","@a11y-ngx/overlay-base":"^1.0.2"},"_hasShrinkwrap":false,"peerDependencies":{"@angular/core":">=12.2.0 <21.0.0","@angular/common":">=12.2.0 <21.0.0"},"_npmOperationalInternal":{"tmp":"tmp/overlay_1.0.4_1764078714813_0.47113075650827385","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@a11y-ngx/overlay","version":"1.0.5","keywords":["overlay","position","positioning","reposition","viewport","boundary","overflow","component","directive","scroll","scrolling","resize","accessibility","angular"],"author":{"url":"https://github.com/LDV2k3/","name":"Luciano Del Vacchio","email":"lucho.development@gmail.com"},"license":"MPL-2.0","_id":"@a11y-ngx/overlay@1.0.5","maintainers":[{"name":"ldv","email":"lucho.development@gmail.com"}],"homepage":"https://github.com/LDV2k3/a11y-libraries/tree/master/projects/a11y-ngx/overlay#readme","bugs":{"url":"https://github.com/LDV2k3/a11y-libraries/issues","email":"lucho.development@gmail.com"},"dist":{"shasum":"31dbcfc2e04820433928bd73018ba1b44e02889a","tarball":"https://registry.npmjs.org/@a11y-ngx/overlay/-/overlay-1.0.5.tgz","fileCount":44,"integrity":"sha512-XE9GS4GoKer9x4XkZWCIrcP/kOtQI56T9vH/9Tj0zVJh9dHyAWMB8bIM+LsA6/FpuQ4Mq6iWrLs0r6X4KMeGCA==","signatures":[{"sig":"MEYCIQCgpmZUCsbbBMn0AkDc5Khpw4VJcoO/FlBL0MDpYavbpgIhAJsKgq0mzm9CvwPwmybeEDxJDLdtPN67oaQdzXQaYu2r","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":977735},"main":"bundles/a11y-ngx-overlay.umd.js","es2015":"fesm2015/a11y-ngx-overlay.js","module":"fesm2015/a11y-ngx-overlay.js","esm2015":"esm2015/a11y-ngx-overlay.js","gitHead":"6c99bb0aa73df7590f7715df592252d4bc968ccd","typings":"a11y-ngx-overlay.d.ts","_npmUser":{"name":"ldv","email":"lucho.development@gmail.com"},"fesm2015":"fesm2015/a11y-ngx-overlay.js","_npmVersion":"8.19.4","description":"A floating overlay-style element that stays within the visible area of the viewport or a given custom boundary (like containers with overflow), preventing it from going off-screen during scroll or window resize","directories":{},"sideEffects":false,"_nodeVersion":"16.20.2","dependencies":{"tslib":"^1.10.0","@a11y-ngx/tab-cycle":"^1.0.2","@a11y-ngx/dom-helper":"^1.1.1","@a11y-ngx/color-scheme":"^1.0.8","@a11y-ngx/overlay-base":"^1.0.2"},"_hasShrinkwrap":false,"peerDependencies":{"@angular/core":">=12.2.0 <21.0.0","@angular/common":">=12.2.0 <21.0.0"},"_npmOperationalInternal":{"tmp":"tmp/overlay_1.0.5_1764252080252_0.3910425660536059","host":"s3://npm-registry-packages-npm-production"}},"1.0.6":{"name":"@a11y-ngx/overlay","version":"1.0.6","keywords":["overlay","position","positioning","reposition","viewport","boundary","overflow","component","directive","scroll","scrolling","resize","accessibility","accessible","angular"],"author":{"url":"https://github.com/LDV2k3/","name":"Luciano Del Vacchio","email":"lucho.development@gmail.com"},"license":"MPL-2.0","_id":"@a11y-ngx/overlay@1.0.6","maintainers":[{"name":"ldv","email":"lucho.development@gmail.com"}],"homepage":"https://github.com/LDV2k3/a11y-libraries/tree/master/projects/a11y-ngx/overlay#readme","bugs":{"url":"https://github.com/LDV2k3/a11y-libraries/issues","email":"lucho.development@gmail.com"},"dist":{"shasum":"17caec1cab67f49c4caeb06a449a87516a1e891c","tarball":"https://registry.npmjs.org/@a11y-ngx/overlay/-/overlay-1.0.6.tgz","fileCount":44,"integrity":"sha512-27OjNLq38/00mTQJIC5ohrxfcBu3EGgaoQCLxKwb86vXeefWsYBhQ6DR3DF0CM4mB/+EbhFOatvd3I4uVLXeyQ==","signatures":[{"sig":"MEYCIQCzmkIX+iOYbv/2Jg5XtyFL+YMeJ82qkKIXu3D8bUf3uAIhANWp5UATeLTbhnaACOPDtwVZfdO3ZkbQkfyAkkN4xv8h","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":962192},"main":"bundles/a11y-ngx-overlay.umd.js","es2015":"fesm2015/a11y-ngx-overlay.js","module":"fesm2015/a11y-ngx-overlay.js","esm2015":"esm2015/a11y-ngx-overlay.js","gitHead":"dba7b40a7903d0219240b633a1936de39eeac765","typings":"a11y-ngx-overlay.d.ts","_npmUser":{"name":"ldv","email":"lucho.development@gmail.com"},"fesm2015":"fesm2015/a11y-ngx-overlay.js","_npmVersion":"8.19.4","description":"A floating overlay-style element that stays within the visible area of the viewport or a given custom boundary (like containers with overflow), preventing it from going off-screen during scroll or window resize","directories":{},"sideEffects":false,"_nodeVersion":"16.20.2","dependencies":{"tslib":"^1.10.0","@a11y-ngx/tab-cycle":"^1.0.2","@a11y-ngx/dom-helper":"^1.1.1","@a11y-ngx/color-scheme":"^1.0.9","@a11y-ngx/overlay-base":"^1.0.2"},"_hasShrinkwrap":false,"peerDependencies":{"@angular/core":">=12.2.0 <21.0.0","@angular/common":">=12.2.0 <21.0.0"},"_npmOperationalInternal":{"tmp":"tmp/overlay_1.0.6_1767620296239_0.05101733254880414","host":"s3://npm-registry-packages-npm-production"}},"1.0.7":{"name":"@a11y-ngx/overlay","version":"1.0.7","description":"A floating overlay-style element that stays within the visible area of the viewport or a given custom boundary (like containers with overflow), preventing it from going off-screen during scroll or window resize","keywords":["overlay","position","positioning","reposition","viewport","boundary","overflow","component","directive","scroll","scrolling","resize","accessibility","accessible","angular"],"homepage":"https://github.com/LDV2k3/a11y-libraries/tree/master/projects/a11y-ngx/overlay#readme","bugs":{"url":"https://github.com/LDV2k3/a11y-libraries/issues","email":"lucho.development@gmail.com"},"license":"MPL-2.0","author":{"name":"Luciano Del Vacchio","email":"lucho.development@gmail.com","url":"https://github.com/LDV2k3/"},"peerDependencies":{"@angular/common":">=12.2.0 <21.0.0","@angular/core":">=12.2.0 <21.0.0"},"dependencies":{"tslib":"^1.10.0","@a11y-ngx/overlay-base":"^1.1.1","@a11y-ngx/tab-cycle":"^1.0.2","@a11y-ngx/dom-helper":"^1.1.1","@a11y-ngx/color-scheme":"^1.0.10"},"main":"bundles/a11y-ngx-overlay.umd.js","module":"fesm2015/a11y-ngx-overlay.js","es2015":"fesm2015/a11y-ngx-overlay.js","esm2015":"esm2015/a11y-ngx-overlay.js","fesm2015":"fesm2015/a11y-ngx-overlay.js","typings":"a11y-ngx-overlay.d.ts","sideEffects":false,"gitHead":"2263df659d5233fb5127e7bd540a2cb3a8f1ac67","_id":"@a11y-ngx/overlay@1.0.7","_nodeVersion":"16.20.2","_npmVersion":"8.19.4","dist":{"integrity":"sha512-rPHXuBFiPY0ZQsT+cTIYD4VRQNtnLCJfmf84+/UItUrmojBX3c+tX8tlllRX3IyC6SorexlaXHfXb3zersNHRw==","shasum":"b5681f10b54446583082e046933008f40d785c58","tarball":"https://registry.npmjs.org/@a11y-ngx/overlay/-/overlay-1.0.7.tgz","fileCount":44,"unpackedSize":967176,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCoyZaUyHLIEN+xTqZA8F7+2owg0jmLFMmQHhyuv2HCkAIgV20Nf4aVLhp070AwgHhrSDml29mC6t6bh+wSOLpMRb8="}]},"_npmUser":{"name":"ldv","email":"lucho.development@gmail.com"},"directories":{},"maintainers":[{"name":"ldv","email":"lucho.development@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/overlay_1.0.7_1771021401330_0.9571500722614696"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-09T22:26:36.986Z","modified":"2026-02-13T22:23:21.686Z","1.0.0":"2025-10-09T22:26:37.321Z","1.0.1":"2025-10-09T22:32:11.833Z","1.0.2":"2025-10-31T13:13:27.897Z","1.0.3":"2025-10-31T15:09:37.443Z","1.0.4":"2025-11-25T13:51:55.031Z","1.0.5":"2025-11-27T14:01:20.486Z","1.0.6":"2026-01-05T13:38:16.413Z","1.0.7":"2026-02-13T22:23:21.517Z"},"bugs":{"url":"https://github.com/LDV2k3/a11y-libraries/issues","email":"lucho.development@gmail.com"},"author":{"name":"Luciano Del Vacchio","email":"lucho.development@gmail.com","url":"https://github.com/LDV2k3/"},"license":"MPL-2.0","homepage":"https://github.com/LDV2k3/a11y-libraries/tree/master/projects/a11y-ngx/overlay#readme","keywords":["overlay","position","positioning","reposition","viewport","boundary","overflow","component","directive","scroll","scrolling","resize","accessibility","accessible","angular"],"description":"A floating overlay-style element that stays within the visible area of the viewport or a given custom boundary (like containers with overflow), preventing it from going off-screen during scroll or window resize","maintainers":[{"name":"ldv","email":"lucho.development@gmail.com"}],"readme":"# Overlay\r\n\r\n- An Angular directive and component to show any content within a floating overlay-style element, seamlessly positioned relative to its trigger.\r\n- The overlay automatically repositions itself on scroll or window resize to remain fully visible within the viewport or its boundary.\r\n\r\nThe main goal of this library is to prevent any common accessibility pitfalls, like _losing_ the opened element within containers with overflow, not being automatically repositioned on scroll or window resize (specially for keyboard users), etc.\r\n\r\n![Angular support from version 12 up to version 20](https://img.shields.io/badge/Angular-v12_to_v20-darkgreen?logo=angular)\r\n\r\nThis library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 12.2.0 to ensure compatibility with a wide range of Angular versions. It has been tested up to v20.\r\n\r\n## Index\r\n\r\n- [Installation](#installation)\r\n- [The Configuration Object](#the-configuration-object)\r\n - [Configuration of the Module](#configuration-of-the-module)\r\n - [The `rootConfig()` method](#the-rootconfig-method)\r\n - [The `customConfig()` method](#the-customconfig-method)\r\n - [The Overlay Config](#the-overlay-config)\r\n - [The Base Config](#the-base-config)\r\n - [The Behavior Config](#the-behavior-config)\r\n - [The Styles Config](#the-styles-config)\r\n - [The Color Scheme Config](#the-color-scheme-config)\r\n - [The Overlay Internal Config](#the-overlay-internal-config)\r\n - [The Trigger Element](#the-trigger-element)\r\n - [The Position Input](#the-position-input)\r\n - [The Positions Allowed Input](#the-positions-allowed-input)\r\n - [The Alignments Allowed Input](#the-alignments-allowed-input)\r\n - [The Position Strategy](#the-position-strategy)\r\n - [The Custom Boundary](#the-custom-boundary)\r\n - [The Safe Space](#the-safe-space)\r\n - [The Safe Space Off](#the-safe-space-off)\r\n - [The Safe Space On](#the-safe-space-on)\r\n - [The Safe Space and zIndex Issues](#the-safe-space-and-zindex-issues)\r\n - [The Fluid Alignment](#the-fluid-alignment)\r\n - [The Fluid Alignment On or Off](#the-fluid-alignment-on-or-off)\r\n - [The Fluid Size](#the-fluid-size)\r\n - [The Fluid Size On or Off](#the-fluid-size-on-or-off)\r\n - [The Viewport Size](#the-viewport-size)\r\n - [The Viewport Safe Size](#the-viewport-safe-size)\r\n - [The Viewport Safe Size Without a Boundary](#the-viewport-safe-size-without-a-boundary)\r\n - [The Viewport Safe Size With a Boundary](#the-viewport-safe-size-with-a-boundary)\r\n - [The Overlay Custom Config](#the-overlay-custom-config)\r\n - [The Selector](#the-selector)\r\n - [The Arrow Size](#the-arrow-size)\r\n - [The Offset Size](#the-offset-size)\r\n - [The Fade Timeout](#the-fade-timeout)\r\n - [The Fade Delay Timeout](#the-fade-delay-timeout)\r\n - [The zIndex](#the-zindex)\r\n - [The Padding](#the-padding)\r\n - [The Shadow](#the-shadow)\r\n - [The Background Color](#the-background-color)\r\n - [The Text Color](#the-text-color)\r\n - [The Border Size](#the-border-size)\r\n - [The Border Color](#the-border-color)\r\n - [The Border Radius](#the-border-radius)\r\n - [The Max Width](#the-max-width)\r\n - [The Max Height](#the-max-height)\r\n - [The Class Names](#the-class-names)\r\n - [The Types](#the-types)\r\n - [The Overlay Position](#the-overlay-position)\r\n - [The Overlay Reposition](#the-overlay-reposition)\r\n - [The Overlay Reposition by Square Areas](#the-overlay-reposition-by-square-areas)\r\n - [The Overlay Alignment](#the-overlay-alignment)\r\n - [The Overlay Alignment Horizontally](#the-overlay-alignment-horizontally)\r\n - [The Overlay Alignment Vertically](#the-overlay-alignment-vertically)\r\n - [The Overlay Realignment](#the-overlay-realignment)\r\n- [The Directive or the Component?](#the-directive-or-the-component)\r\n- [The Overlay Directive](#the-overlay-directive)\r\n - [The Directive Inputs](#the-directive-inputs)\r\n - [The Config Input](#the-config-input)\r\n - [The Config Input Examples](#the-config-input-examples)\r\n - [The Config Input through an Object](#the-config-input-through-an-object)\r\n - [The Config Input through a String](#the-config-input-through-a-string)\r\n - [The Config Input through the `OverlayCreateService`](#the-config-input-through-the-overlaycreateservice)\r\n - [The Directive Outputs](#the-directive-outputs)\r\n - [The Directive public Methods, Properties, Getters and Setters](#the-directive-public-methods-properties-getters-and-setters)\r\n - [The Directive `setOverlayConfig()` Method](#the-directive-setoverlayconfig-method)\r\n - [The Directive `setStyles()` Method](#the-directive-setstyles-method)\r\n - [The Directive `setCustomSelector()` Method](#the-directive-setcustomselector-method)\r\n - [The Directive `show()` Method](#the-directive-show-method)\r\n - [The Directive `hide()` Method](#the-directive-hide-method)\r\n - [The Directive `toggle()` Method](#the-directive-toggle-method)\r\n - [The Directive Listeners](#the-directive-listeners)\r\n - [The Directive Close Listeners](#the-directive-close-listeners)\r\n - [The Directive Close on Escape Listener](#the-directive-close-on-escape-listener)\r\n - [The Directive Close on Click Outside Listener](#the-directive-close-on-click-outside-listener)\r\n - [The Directive Tab Cycle Listener](#the-directive-tab-cycle-listener)\r\n - [The Directive Focus on Overlay First](#the-directive-focus-on-overlay-first)\r\n- [The Overlay Component](#the-overlay-component)\r\n- [The Overlay Arrow Component](#the-overlay-arrow-component)\r\n - [The Arrow Component inside the Directive](#the-arrow-component-inside-the-directive)\r\n- [The Overlay Create Service](#the-overlay-create-service)\r\n - [The Service Create Method](#the-service-create-method)\r\n - [The Service Create Method using an `HTMLElement` trigger](#the-service-create-method-using-an-htmlelement-trigger)\r\n - [The Service Create Method using a `DOMRect` trigger](#the-service-create-method-using-a-domrect-trigger)\r\n - [The Service Destroy Method](#the-service-destroy-method)\r\n- [The Color Schemes](#the-color-schemes)\r\n - [How to Configure the Color Schemes](#how-to-configure-the-color-schemes)\r\n - [How to Force a Scheme](#how-to-force-a-scheme)\r\n - [How to add a New Color Scheme](#how-to-add-a-new-color-scheme)\r\n- [Examples](#examples)\r\n - [The Component Use](#the-component-use)\r\n - [The Directive Use](#the-directive-use)\r\n - [The Responsive Table](#the-responsive-table)\r\n - [The Context Menu](#the-context-menu)\r\n\r\n## Installation\r\n\r\n1. Install npm package:\r\n\r\n `npm install @a11y-ngx/overlay --save`\r\n\r\n2. Import `A11yOverlayModule` into your module or standalone component:\r\n\r\n```typescript\r\nimport { A11yOverlayModule } from '@a11y-ngx/overlay';\r\n\r\n@NgModule({\r\n declarations: [...],\r\n imports: [\r\n ...\r\n A11yOverlayModule,\r\n ],\r\n})\r\nexport class AppModule { }\r\n```\r\n\r\n> **CHECK ALSO:** The [rootConfig()](#the-rootconfig-method) and [customConfig()](#the-customconfig-method) methods.\r\n\r\n## The Configuration Object\r\n\r\n[Check the Types](#the-types) to better understand each property.\r\n\r\n### Configuration of the Module\r\n\r\nThe module can be configured at a:\r\n\r\n- **Root Level**:
\r\n Using [the `rootConfig()` method](#the-rootconfig-method) and providing a config object of type [`OverlayRootConfig`](#the-overlay-config).\r\n- **Custom Level**:
\r\n Using [the `customConfig()` method](#the-customconfig-method) and providing a config object of type [`OverlayCustomConfig`](#the-overlay-custom-config).\r\n\r\n#### The `rootConfig()` method\r\n\r\nServes to establish and override the global default configuration.\r\n\r\n> ⚠️ **IMPORTANT:**\r\n>\r\n> ❗❗ **DO NOT use it on a library or a low level component within your app**, since this method is meant to be called only once, the idea is to use it at a root level on the main app.\r\n>\r\n> On a library or sub-module, you can use [the `customConfig()` method](#the-customconfig-method).\r\n\r\nAccepts a single parameter `config` of type [`OverlayRootConfig`](#the-overlay-config).\r\n\r\n**On Angular v12 - v14:**\r\n\r\n```typescript\r\nA11yOverlayModule.rootConfig({\r\n arrowSize: 5,\r\n offsetSize: 10,\r\n safeSpace: { top: 65, left: 50 },\r\n}),\r\n```\r\n\r\n**On Angular v15+:**\r\n\r\n```typescript\r\nprovideA11yOverlay({\r\n arrowSize: 5,\r\n offsetSize: 10,\r\n safeSpace: { top: 65, left: 50 },\r\n}),\r\n```\r\n\r\n#### The `customConfig()` method\r\n\r\nServes to establish a sub level configuration based on a given `selector`.\r\n\r\n> **IMPORTANT:** Everything established within a `customConfig()` it's going to _look back_ for missing properties. Meaning that, if you only set (as the example below) only 2 values, the rest will be filled out checking the globals (set in the `rootConfig()`, if any) and then the defaults.\r\n\r\nAccepts a single parameter `config` of type [`OverlayCustomConfig`](#the-overlay-custom-config).\r\n\r\n**On Angular v12 - v14:**\r\n\r\n```typescript\r\nA11yOverlayModule.customConfig({\r\n selector: 'my-custom-component',\r\n arrowSize: 0,\r\n positionStrategy: 'absolute',\r\n}),\r\n```\r\n\r\n**On Angular v15+:**\r\n\r\n```typescript\r\nprovideA11yOverlayFeature({\r\n selector: 'my-custom-component',\r\n arrowSize: 0,\r\n positionStrategy: 'absolute',\r\n}),\r\n```\r\n\r\n> **Use case**:\r\n>\r\n> In the above example, by providing the selector `'my-custom-component'`, it will create a sub set of custom properties and styles for all overlays rendered inside that selector.\r\n>\r\n> In this particular case, those overlays will not have an arrow, while the rest (outside that selector) will have arrows of `5px`, since that was the value set in `rootConfig()`.\r\n\r\n### The Overlay Config\r\n\r\n`OverlayRootConfig` is a `Partial<>` of `OverlayConfig`.\r\n\r\nIt extends from 4 other types:\r\n\r\n- The [Config Base Type](#the-base-config).\r\n- The [Config Behavior Type](#the-behavior-config).\r\n- The [Config Styles Type](#the-styles-config).\r\n- The [Config Color Scheme Type](#the-color-scheme-config).\r\n\r\nSome other config types:\r\n\r\n- The [Internal Config Type](#the-overlay-internal-config).\r\n- The [Custom Config Type](#the-overlay-custom-config).\r\n\r\n#### The Base Config\r\n\r\n- **Dependency:** [`Overlay Base abstract class`](https://www.npmjs.com/package/@a11y-ngx/overlay-base).\r\n- **Type:** `OverlayBaseConfig`.\r\n- **Properties:**\r\n\r\n | Property | Type | Description |\r\n | :------- | :--- | :---------- |\r\n | `position` | `OverlayPositionInput` | See [the Position Input](#the-position-input) |\r\n | `positionStrategy` | `OverlayPositionStrategy` | See [the Position Strategy](#the-position-strategy) |\r\n | `positionsAllowed` | `OverlayPositionsAllowedInput` | See [the Positions Allowed Input](#the-positions-allowed-input) |\r\n | `alignmentsAllowed` | `OverlayAlignmentsAllowedInput` | See [the Alignments Allowed Input](#the-alignments-allowed-input) |\r\n | `safeSpace` | `OverlaySafeSpace` | See [the Safe Space](#the-safe-space) |\r\n | `fluidAlignment` | `boolean` | See [the Fluid Alignment](#the-fluid-alignment) |\r\n | `fluidSize` | `boolean` | See [the Fluid Size](#the-fluid-size) |\r\n | `allowScrollListener` | `boolean` | See [the Page Scroll Listener](https://www.npmjs.com/package/@a11y-ngx/overlay-base#the-page-scroll-listener) (from the Base Class library) |\r\n\r\n#### The Behavior Config\r\n\r\n- **Type:** `OverlayConfigBehavior`.\r\n- **Properties:**\r\n\r\n | Property | Type | Description |\r\n | :------- | :--- | :---------- |\r\n | `allowClose` | `OverlayAllowClose` or `boolean` | See [the Close Listeners](#the-directive-close-listeners) |\r\n | `allowTabCycle` | `boolean` | See [the Tab-Cycle Listener](#the-directive-tab-cycle-listener) |\r\n | `firstFocusOn` | `'first'` or `'last'` or `undefined` | See [the Tab-Cycle Focus First](#the-directive-focus-on-overlay-first) |\r\n\r\n#### The Styles Config\r\n\r\nAll color related default values (★) are coming from the variables set within [the Color Scheme global configuration](https://www.npmjs.com/package/@a11y-ngx/color-scheme#user-content-global-config-basic-properties).\r\n\r\n- **Type:** `OverlayConfigStyles`.\r\n- **Properties:**\r\n\r\n | Property | Type | Description |\r\n | :------- | :--- | :---------- |\r\n | `arrowSize` | `number` | See [the Arrow Size](#the-arrow-size) |\r\n | `offsetSize` | `number` | See [the Offset Size](#the-offset-size) |\r\n | `fadeMs` | `number` | See [the Fade Timeout](#the-fade-timeout) |\r\n | `fadeDelayMs` | `number` | See [the Fade Delay Timeout](#the-fade-delay-timeout) |\r\n | `zIndex` | `number` | See [the zIndex](#the-zindex) |\r\n | `padding` | `string` | See [the Padding](#the-padding) |\r\n | `shadow` ★ | `string` | See [the Shadow](#the-shadow) |\r\n | `shadowColor` ★ | `string` | See [the Shadow](#the-shadow) |\r\n | `backgroundColor` ★ | `string` | See [the Background Color](#the-background-color) |\r\n | `textColor` ★ | `string` | See [the Text Color](#the-text-color) |\r\n | `borderSize` | `number` | See [the Border Size](#the-border-size) |\r\n | `borderColor` ★ | `string` | See [the Border Color](#the-border-color) |\r\n | `borderRadius` | `number` | See [the Border Radius](#the-border-radius) |\r\n | `className` | `string` or `string[]` | See [the Class Names](#the-class-names) |\r\n | `maxWidth` | `string` | See [the Max Width](#the-max-width) |\r\n | `maxHeight` | `string` | See [the Max Height](#the-max-height) |\r\n\r\n#### The Color Scheme Config\r\n\r\n- **Dependency:** [Color Scheme library](https://www.npmjs.com/package/@a11y-ngx/color-scheme#the-color-scheme-config-styles-config).\r\n- **Type:** `ColorSchemeStylesConfig`.\r\n- **Properties:**\r\n\r\n | Property | Type | Description |\r\n | :------- | :--- | :---------- |\r\n | `colorSchemes` | `Object` | See [how to Configure the Color Schemes](#how-to-configure-the-color-schemes) |\r\n | `forceScheme` | `ColorScheme` | See [how to Force a Scheme](#how-to-force-a-scheme) |\r\n\r\n#### The Overlay Internal Config\r\n\r\nThis type contains properties that are mostly being used inside [the Overlay Base Config Object](https://www.npmjs.com/package/@a11y-ngx/overlay-base#the-configuration-object).\r\n\r\n- **Type:** `OverlayInternalConfig`.\r\n- **Properties:**\r\n - [`trigger`](#the-trigger-element).\r\n - [`position`](#the-position-input).\r\n - [`positionStrategy`](#the-position-strategy).\r\n - [`boundary`](#the-custom-boundary).\r\n - [`safeSpace`](#the-safe-space).\r\n - [`offsetSize`](#the-offset-size).\r\n - [`fluidAlignment`](#the-fluid-alignment).\r\n - [`fluidSize`](#the-fluid-size).\r\n - [`positionsAllowed`](#the-positions-allowed-input).\r\n - [`alignmentsAllowed`](#the-alignments-allowed-input).\r\n - [`allowScrollListener`](https://www.npmjs.com/package/@a11y-ngx/overlay-base#the-page-scroll-listener) (from the Base Class library).\r\n\r\n##### The Trigger Element\r\n\r\nIt is the _area_ from which the overlay will be relatively positioned.\r\n\r\n- **Input / Config Property:** `trigger`.\r\n- **Type:** `HTMLElement` or `DOMRect`.\r\n\r\nWhen `HTMLElement` is provided (such as a `\r\n \r\n My Big Tooltip\r\n \r\n\r\n \r\n \r\n \r\n My Big Tooltip\r\n \r\n\r\n```\r\n\r\nIn the above example, the overlay at the left has the `[boundary]` set with the element `myBoundary` and the one at the right has not.\r\n\r\nNow, considering that the default position/alignment is set to `top-center`, the one at the left it's contained by the boundary limits and will be repositioned at the bottom, and since is wider than the trigger and can't be centered, it will be aligned to the start.\r\n\r\nThe one at the right will ignore the boundary completely and, therefore, will be positioned at `top` and aligned to the `center`.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-boundary-on.jpg)\r\n\r\nThe use of boundaries can be helpful when we have containers with overflow (such as [responsive tables](#the-responsive-table)).\r\n\r\n> ⚠️ **IMPORTANT:** for the given example below, and because of the possibility of an overflow, the boundary should be styled with `position: relative;` and the overlays inside should use `positionStrategy=\"absolute\"`. See [The Position Strategy](#the-position-strategy) and [the Responsive Table example](#the-responsive-table).\r\n>\r\n> ![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-boundary-fixed-absolute.jpg)\r\n\r\n##### The Safe Space\r\n\r\nTo establish an extra safe space to the viewport's edges in case some fixed areas are present, such as headers, side menus or footers.\r\n\r\nThis way, the overlay will consider this area as the _edge limit_ and reposition itself if reached. Most useful use cases are related to scroll events.\r\n\r\n- **Input / Config Property:** `safeSpace`.\r\n- **Type:** `OverlaySafeSpace`:\r\n - `object` with each side as a property of type `number`.\r\n- **Default:** `{ top: 0, bottom: 0, left: 0, right: 0 }`.\r\n\r\n###### The Safe Space Off\r\n\r\nIn this scenario we can see two different overlays with the default position/alignment (`top-center`) when the safe space is not set at all.\r\n\r\nBoth overlays have enough space at the top and can be centered.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-safe-space-off.jpg)\r\n\r\n###### The Safe Space On\r\n\r\nLet's say we have a header at the top (`65px`) and a left side menu (`50px`), both fixed to the page.\r\n\r\nNow we set the safe space with the desired values for our fixed landmarks:\r\n\r\n```typescript\r\nA11yOverlayModule.rootConfig({\r\n safeSpace: { top: 65, left: 50 },\r\n}),\r\n```\r\n\r\n> **NOTE:** For the next examples, we have forced the right overlay to ignore the safe space.\r\n\r\nThe overlay at the left doesn't have enough space to be centered anymore and it will analyze where can be aligned, which will result at `start`.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-safe-space-on-no-scroll.jpg)\r\n\r\nNow we start scrolling down and, the moment the left overlay reaches the top safe space limit, it will need to check the best side to reposition itself, which will result at `bottom`.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-safe-space-on-scroll.jpg)\r\n\r\nWe keep scrolling down and we can see the right overlay not repositioning and overlapping the header. This can be **an issue** depending on what `z-index` your landmarks are set. See [the Safe Space and zIndex Issues](#the-safe-space-and-zindex-issues).\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-safe-space-on-scroll-overlapping.jpg)\r\n\r\n###### The Safe Space and zIndex Issues\r\n\r\nThe overlay `z-index` value is set to `9999` by default.\r\n\r\nThis means that if, for instance, your header is _also_ set to `z-index: 9999;`, it will lead to leave the trigger behind, but not the overlay.\r\n\r\n> **NOTE:** For this particular scenario, lets change the header and the top safe space to `100px`.\r\n\r\nSo, while the overlay has not reached the viewport's top edge limit, we can still see it, but only a third of the trigger:\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-safe-space-on-scroll-issue-01.jpg)\r\n\r\nAnd if we keep scrolling down, now the overlay has repositioned to the `bottom`, is still over the header but it doesn't seem to be \"visually\" attached to any trigger.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-safe-space-on-scroll-issue-02.jpg)\r\n\r\nTo avoid this issue, we can globally set the `z-index` to a lower value than our landmarks by using [the `rootConfig()` method](#the-rootconfig-method).\r\n\r\n##### The Fluid Alignment\r\n\r\nTo establish whether the overlay's alignment will stick to the edges of the viewport/boundary (if set to `true`) or make jumps between `start`, `center` or `end` (if set to `false`).\r\n\r\n- **Input / Config Property:** `fluidAlignment`.\r\n- **Type:** `boolean`.\r\n- **Default:** `false`.\r\n\r\n###### The Fluid Alignment On or Off\r\n\r\nIf `fluidAlignment` is on, and the overlay width (or height) exceeds both, the trigger's size and the free space to be centered, it will stick to the closest viewport/boundary edge. If not (is off), it will use one of the edges of the trigger to align itself (`start` or `end`).\r\n\r\nIn the next example, the overlay on the left is the only one that has `fluidAlignment` set to `true`, which means that it's going to be aligned to the left side of the viewport, while the one on the right should respect either `start`, `center` or `end` (in this case) of its trigger.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-fluid-alignment-on-off.jpg)\r\n\r\nWhen this option is on, and the overlay is sticked to one of the sides (the left one in this case), as shown in the example above, you can access the property `overlayOutside` with the side that it is out, as its value (`'left'`).\r\n\r\n##### The Fluid Size\r\n\r\nTo establish whether the overlay size will adjust to the free space (if set to `true`) or stay as its original size, with the possibility of being out of the visible area, if larger (if set to `false`).\r\n\r\n- **Input / Config Property:** `fluidSize`.\r\n- **Type:** `boolean`.\r\n- **Default:** `true`.\r\n\r\nThe size adjustment will depend of the overlay's position:\r\n\r\n- if `top` or `bottom`, the `height` of the overlay will be adjusted to the free space of any of those sides.\r\n- if `left` or `right`, the `width` of the overlay will be adjusted to the free space of any of those sides.\r\n\r\n###### The Fluid Size On or Off\r\n\r\nIf `fluidSize` is on, and the overlay is bigger than the chosen side free space, it will auto adapt its size. If not (is off), it will respect the original size and could be partially off screen.\r\n\r\nIn the next example, both overlays have the same `maxWidth` value of `300px`, but only the one on the left has `fluidSize` set to `true`. The `maxHeight` is not set, which will result on automatic calculation based on its content.\r\n\r\nThis means that the one on the left it's going to auto adapt its size to the maximum top space (`193px` of height, without the arrow/offset sizes into consideration), while the one on the right will be partially off the screen, since its max content makes it `262px` of height.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-fluid-size-on-off.jpg)\r\n\r\nCheck also [the square areas](#the-overlay-reposition-by-square-areas) to better understand how the free space is calculated in case the overlay size exceeds it.\r\n\r\n##### The Viewport Size\r\n\r\nThe viewport size (without the scrollbars into consideration).\r\n\r\n- **Type:** `ViewportSize`:\r\n - `object` with `width` and `height` as a property of type `number`.\r\n- **Default:** viewport's width and height.\r\n\r\n##### The Viewport Safe Size\r\n\r\nThe viewport safe size is the result of how many free space (`width` and `height`) the overlay can consider to be positioned.\r\n\r\nIt will be the calculation between the [viewport size](#the-viewport-size), a given [custom boundary](#the-custom-boundary) (also without the scrollbars into consideration, if any) and/or the [safe space](#the-safe-space).\r\n\r\n- **Type:** `ViewportSize`.\r\n\r\nIn the following two examples, the green area is the so called _viewport **safe** size_, meaning that the overlay will consider only that area to establish its position and alignment.\r\n\r\n###### The Viewport Safe Size Without a Boundary\r\n\r\nImagine having a viewport of `755px` of width and `415px` of height and two safe spaces, one at the `top` of `65px` and another at the `left` of `50px`.\r\n\r\nIn this case, the _safe size_ will be the result of:\r\n\r\n- the viewport's `width` minus the `left` safe space: `755 - 50 = 705px`.\r\n- the viewport's `height` minus the `top` safe space `415 - 65 = 350px`.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-viewport-safe-size-without-boundary.jpg)\r\n\r\n###### The Viewport Safe Size With a Boundary\r\n\r\nNow imagine having the same viewport (`755px` by `415px`), the same safe spaces (`65px` and `50px`) and a [custom boundary](#the-custom-boundary) of `730px` of `width` and `240px` of `height`. This boundary is, in this examnple, by design, partially behind the left safe space.\r\n\r\nThe _safe size_ will be the result of the custom boundary size minus the safe space area that is overlapping at its left side.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-viewport-safe-size-with-boundary.jpg)\r\n\r\n#### The Overlay Custom Config\r\n\r\nThis type contains properties to customize the overlay and it is used in the [`customConfig() method`](#the-customconfig-method) and inside either [the Component](#the-overlay-component) or [the Directive](#the-overlay-directive).\r\n\r\nIt also extends the properties from [the Overlay Config](#the-overlay-config) and [the Internal Config](#the-overlay-internal-config).\r\n\r\n- **Type:** `OverlayCustomConfig`.\r\n- **Properties:**\r\n - [`selector`](#the-selector).\r\n - [`arrowSize`](#the-arrow-size).\r\n - [`fadeMs`](#the-fade-timeout).\r\n - [`fadeDelayMs`](#the-fade-delay-timeout).\r\n - [`zIndex`](#the-zindex).\r\n - [`padding`](#the-padding).\r\n - [`shadow`](#the-shadow).\r\n - [`backgroundColor`](#the-background-color).\r\n - [`textColor`](#the-text-color).\r\n - [`borderSize`](#the-border-size).\r\n - [`borderColor`](#the-border-color).\r\n - [`borderRadius`](#the-border-radius).\r\n - [`maxWidth`](#the-max-width).\r\n - [`maxHeight`](#the-max-height).\r\n - [`className`](#the-class-names).\r\n - [`allowTabCycle`](#the-directive-tab-cycle-listener).\r\n - [`allowClose`](#the-directive-close-listeners).\r\n\r\n##### The Selector\r\n\r\nIt defines the selector of the element where all behavior and styles will be applied to.\r\n\r\n- **Config Property:** `selector`.\r\n- **Type:** `string`.\r\n\r\n##### The Arrow Size\r\n\r\nIt defines the size of the arrow.\r\n\r\n- **Input / Config Property:** `arrowSize`.\r\n- **Type:** `number`.\r\n- **Default:** `7`.\r\n- **Accepts:** zero or greater.\r\n- **Translated to:** _pixels_.\r\n- **CSS Variable:** `--overlay-arrow`.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-arrow-size.jpg)\r\n\r\n##### The Offset Size\r\n\r\nIt defines the space between the overlay and its trigger.\r\n\r\n- **Input / Config Property:** `offsetSize`.\r\n- **Type:** `number`.\r\n- **Default:** `5`.\r\n- **Accepts:** positives and negatives.\r\n- **Translated to:** _pixels_.\r\n\r\n> **NOTE:** Even if this property could be considered as a \"style\", it is actually used as an internal calculation within the Overlay Base Class, it doesn't contain a CSS variable.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-offset-size.jpg)\r\n\r\n##### The Fade Timeout\r\n\r\nIt defines the timeout to fade in or out the overlay.\r\n\r\n> **NOTE:** The value will result on the combination between _this value_ and `fadeDelayMs` value.\r\n\r\n- **Input / Config Property:** `fadeMs`.\r\n- **Type:** `number`.\r\n- **Default:** `150`.\r\n- **Translated to:** _milliseconds_.\r\n- **CSS Variable:** `--overlay-fade-ms`.\r\n\r\n###### The Fade Delay Timeout\r\n\r\nIt is the time it will take to start to fade in or out after the overlay is shown or hidden.\r\n\r\n- **Input / Config Property:** `fadeDelayMs`.\r\n- **Type:** `number`.\r\n- **Default:** `0`.\r\n- **Translated to:** _milliseconds_.\r\n\r\n##### The zIndex\r\n\r\nIt defines the `z-index` CSS value.\r\n\r\nThis can be helpful for scenarios where the page contains fixed landmarks. See [the Safe Space and zIndex issues](#the-safe-space-and-zindex-issues).\r\n\r\n- **Input / Config Property:** `zIndex`.\r\n- **Type:** `number`.\r\n- **Default:** `9999`.\r\n- **CSS Variable:** `--overlay-zindex`.\r\n\r\n##### The Padding\r\n\r\nIt defines the `padding` CSS value.\r\n\r\n- **Input / Config Property:** `padding`.\r\n- **Type:** `string`.\r\n- **Default:** `'10px 16px'` (`10px` top & bottom, `16px` left & right).\r\n- **CSS Variable:** `--overlay-padding`.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-padding-size.jpg)\r\n\r\n##### The Shadow\r\n\r\nIt defines the `box-shadow` CSS value, by combining two properties:\r\n\r\n- **Input / Config Property:** `shadow`.\r\n - **Type:** `string`.\r\n - **Default:** `var(--a11y-shadow)` _(coming from the [Color Scheme library](https://www.npmjs.com/package/@a11y-ngx/color-scheme#user-content-global-config-basic-properties))_.\r\n - **CSS Variable:** `--overlay-shadow`.\r\n- **Input / Config Property:** `shadowColor`.\r\n - **Type:** `string`.\r\n - **Default:** `var(--a11y-shadow-color)` _(coming from the [Color Scheme library](https://www.npmjs.com/package/@a11y-ngx/color-scheme#user-content-global-config-basic-properties))_.\r\n - **CSS Variable:** `--overlay-shadow-color`.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-shadow.jpg)\r\n\r\n##### The Background Color\r\n\r\nIt defines the `background-color` CSS value.\r\n\r\n- **Input / Config Property:** `backgroundColor`.\r\n- **Type:** `string`.\r\n- **Default:** `var(--a11y-bg-color)` _(coming from the [Color Scheme library](https://www.npmjs.com/package/@a11y-ngx/color-scheme#user-content-global-config-basic-properties))_.\r\n- **CSS Variable:** `--overlay-bg-color`.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-background-color.jpg)\r\n\r\n##### The Text Color\r\n\r\nIt defines the `color` CSS value.\r\n\r\n- **Input / Config Property:** `textColor`.\r\n- **Type:** `string`.\r\n- **Default:** `var(--a11y-text-color)` _(coming from the [Color Scheme library](https://www.npmjs.com/package/@a11y-ngx/color-scheme#user-content-global-config-basic-properties))_.\r\n- **CSS Variable:** `--overlay-text-color`.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-text-color.jpg)\r\n\r\n##### The Border Size\r\n\r\nIt defines the `border-width` CSS value.\r\n\r\n- **Input / Config Property:** `borderSize`.\r\n- **Type:** `number`.\r\n- **Default:** `1`.\r\n- **Translated to:** _pixels_.\r\n- **CSS Variable:** `--overlay-border-size`.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-border-size.jpg)\r\n\r\n##### The Border Color\r\n\r\nIt defines the `border-color` CSS value.\r\n\r\n- **Input / Config Property:** `borderColor`.\r\n- **Type:** `string`.\r\n- **Default:** `var(--a11y-border-color)` _(coming from the [Color Scheme library](https://www.npmjs.com/package/@a11y-ngx/color-scheme#user-content-global-config-basic-properties))_.\r\n- **CSS Variable:** `--overlay-border-color`.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-border-color.jpg)\r\n\r\n##### The Border Radius\r\n\r\nIt defines the `border-radius` CSS value.\r\n\r\n- **Input / Config Property:** `borderRadius`.\r\n- **Type:** `number`.\r\n- **Default:** `5` (same for each corner).\r\n- **Translated to:** _pixels_.\r\n- **CSS Variable:** `--overlay-border-radius`.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-border-radius.jpg)\r\n\r\n##### The Max Width\r\n\r\nIt defines the maximum width allowed for the overlay.\r\n\r\n> **NOTE:** The width of the viewport/boundary are also considered as the maximum width allowed by default, but it's **_really important_** that, if the overlay contains a big amount of text or dynamic content (in terms of width), you set a specific `maxWidth` value.\r\n\r\n- **Input / Config Property:** `maxWidth`.\r\n- **Type:** `string`.\r\n- **Default:** `'auto'`.\r\n- **You can use:** `px`, `em`, `%`, etc.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-max-width.jpg)\r\n\r\n##### The Max Height\r\n\r\nIt defines the maximum height allowed for the overlay.\r\n\r\n- **Input / Config Property:** `maxHeight`.\r\n- **Type:** `string`.\r\n- **Default:** _unset_.\r\n- **You can use:** `px`, `em`, `%`, etc.\r\n\r\n> **NOTE:** The height of the viewport/boundary are also considered as the maximum height allowed by default. When you set a `maxHeight` value and the content exceeds it, a vertical overflow will appear (this _behavior_ applies only for [the Component](#the-overlay-component), since is the one that contains a template with a stylesheet).\r\n>\r\n> If you plan on using [the Directive](#the-overlay-directive), please consider adding `overflow` to an element within the main wrapper.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-max-height.jpg)\r\n\r\n##### The Class Names\r\n\r\nIt defines custom class names for your overlay element.\r\n\r\n- **Config Property:** `className`.\r\n- **Type:** `string` or `string[]`.\r\n- **Default:** _unset_.\r\n\r\n> **NOTE:** This can be useful for custom styles or specific scenarios where [the overlays are created outside the given selector](#the-service-create-method-using-a-domrect-trigger).\r\n\r\n### The Types\r\n\r\n#### The Overlay Position\r\n\r\nMeans the relative position to the trigger.\r\n\r\n- **Type:** `OverlayPosition`.\r\n- **From the Base library `enum`:** `POSITION`.\r\n- **Default:** `'top'`.\r\n- **Values:**\r\n - `'top'`.\r\n - `'bottom'`.\r\n - `'left'`.\r\n - `'right'`.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-position.jpg)\r\n\r\n##### The Overlay Reposition\r\n\r\nThe repositioning will depend on the chosen `position`.\r\n\r\nFor instance, if the overlay position is set to `'top'`, it will check if there is enough space to be placed there. If not, it will try at `'bottom'`, then at `'left'` and finally at `'right'`.\r\n\r\nThe order would be:\r\n\r\n- `'top'` -> `'bottom'` -> `'left'` -> `'right'`.\r\n- `'bottom'` -> `'top'` -> `'left'` -> `'right'`.\r\n- `'left'` -> `'right'` -> `'top'` -> `'bottom'`.\r\n- `'right'` -> `'left'` -> `'top'` -> `'bottom'`.\r\n\r\n> **NOTE:** If at any point, the overlay (especially when `resize` event occurs on the page) doesn't have enough space at any of the allowed sides to fit its maximum size, it will choose the one with [more square area](#the-overlay-reposition-by-square-areas).\r\n>\r\n> Check also [the `fluidSize` On or Off](#the-fluid-size-on-or-off).\r\n\r\n###### The Overlay Reposition by Square Areas\r\n\r\nIn the next scenario, the overlay has a `top` position with `positionsAllowed` set to `'opposite'`, which means only `top` or `bottom` are allowed.\r\n\r\nGiven the current overlay's maximum size is set to `300px` by `262px`, its height exceeds both allowed sides (`205px` at top and `147px` at bottom), so the overlay will choose the one with more available square area:\r\n\r\n- top: `770 x 205 = 157850` ✔️.\r\n- bottom: `770 x 147 = 113190` ❌.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-square-areas.jpg)\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-square-areas-result.jpg)\r\n\r\n#### The Overlay Alignment\r\n\r\nMeans the relative alignment to the trigger.\r\n\r\n- **Type:** `OverlayAlignment`.\r\n- **From the Base library `enum`:** `ALIGNMENT`.\r\n- **Default:** `'center'` (or `'start'` if `alignmentsAllowed` is set to `'edges'`).\r\n- **Values:**\r\n - `'start'`.\r\n - `'center'`.\r\n - `'end'`.\r\n\r\n##### The Overlay Alignment Horizontally\r\n\r\nThis applies for `top` and `bottom` positions.\r\n\r\n- `start`: means aligned to the left side of the trigger.\r\n- `center`: means aligned to the center of the trigger.\r\n- `end`: means aligned to the right side of the trigger.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-alignment-horizontal.jpg)\r\n\r\n##### The Overlay Alignment Vertically\r\n\r\nThis applies for `left` and `right` positions.\r\n\r\n- `start`: means aligned to the top side of the trigger.\r\n- `center`: means aligned to the center of the trigger.\r\n- `end`: means aligned to the bottom side of the trigger.\r\n\r\n![\"\"](https://raw.githubusercontent.com/LDV2k3/a11y-libraries/refs/heads/master/projects/a11y-ngx/overlay/src/lib/images/example-alignment-vertical.jpg)\r\n\r\n##### The Overlay Realignment\r\n\r\nThe realignment will depend on the chosen `alignment`.\r\n\r\nFor instance, if the overlay alignment is set to `'center'`, it will check if there is enough space to be placed there. If not, it will try at `'start'` and finally at `'end'`.\r\n\r\nNow, if `alignmentsAllowed` is set to `'edges'`, checking for `'center'` alignment will be completelly ignored, checking first at `'start'` and finally at `'end'`.\r\n\r\n## The Directive or the Component?\r\n\r\nWhile I strongly recommend using the component, there could be scenarios where you need/want to use the directive.\r\n\r\nHere are the main differences between the component and the directive:\r\n\r\n- [The Component](#the-overlay-component):\r\n - It will handle the content and calculations better, since it contains a template and a stylesheet that already covers all possible scenarios.\r\n - All styles are applied through CSS variables.\r\n - Check [the Component Use](#the-component-use) example.\r\n- [The Directive](#the-overlay-directive):\r\n - It will apply all styles to the host element as inline CSS.\r\n - Check [the Directive Use](#the-directive-use) example.\r\n\r\n## The Overlay Directive\r\n\r\nThe `OverlayDirective` extends from [the `OverlayBase` class library](https://www.npmjs.com/package/@a11y-ngx/overlay-base#the-overlay-base-class).\r\n\r\n- **Selector:** `[a11yOverlay]`.\r\n- **Exported As:** `a11yOverlay`.\r\n\r\nBehind the scenes, this one will take care of:\r\n\r\n- Save/update all the configurations.\r\n- The logic to show, hide and/or toggle.\r\n- Set the position of the overlay when calculated.\r\n- It will create [the Arrow Component](#the-overlay-arrow-component) within the _host_ element, if [`arrowSize`](#the-arrow-size) is set with a value greater than zero.\r\n\r\n### The Directive Inputs\r\n\r\n| Name | Type | Description |\r\n| :--- | :--- | :---------- |\r\n| `config` | `OverlayCustomConfig` or `string` | See [the Overlay Custom Config](#the-overlay-custom-config) or [the Config Input through a `string`](#the-config-input-through-a-string) |\r\n| `trigger` | `HTMLElement` | See [the Trigger element](#the-trigger-element) |\r\n| `boundary` | `HTMLElement` | See [the Custom Boundary](#the-custom-boundary) |\r\n| `position` | `OverlayPositionInput` | See [the Position Input](#the-position-input) |\r\n| `positionsAllowed` | `OverlayPositionsAllowedInput` | See [the Positions Allowed Input](#the-positions-allowed-input) |\r\n| `alignmentsAllowed` | `OverlayAlignmentsAllowedInput` | See [the Alignments Allowed Input](#the-alignments-allowed-input) |\r\n| `fluidAlignment` | `boolean` | See [the Fluid Alignment](#the-fluid-alignment) |\r\n| `fluidSize` | `boolean` | See [the Fluid Size](#the-fluid-size) |\r\n| `positionStrategy` | `OverlayPositionStrategy` | See [the Position Strategy](#the-position-strategy) |\r\n| `safeSpace` | `OverlaySafeSpace` | See [the Safe Space](#the-safe-space) |\r\n| `arrowSize` | `number` | See [the Arrow Size](#the-arrow-size) |\r\n| `offsetSize` | `number` | See [the Offset Size](#the-offset-size) |\r\n| `fadeMs` | `number` | See [the Fade Timeout](#the-fade-timeout) |\r\n| `fadeDelayMs` | `number` | See [the Fade Delay Timeout](#the-fade-delay-timeout) |\r\n| `zIndex` | `number` | See [the zIndex](#the-zindex) |\r\n| `padding` | `string` | See [the Padding](#the-padding) |\r\n| `shadow` | `string` | See [the Shadow](#the-shadow) |\r\n| `shadowColor` | `string` | See [the Shadow](#the-shadow) |\r\n| `backgroundColor` | `string` | See [the Background Color](#the-background-color) |\r\n| `textColor` | `string` | See [the Text Color](#the-text-color) |\r\n| `borderSize` | `string` | See [the Border Size](#the-border-size) |\r\n| `borderColor` | `string` | See [the Border Color](#the-border-color) |\r\n| `borderRadius` | `number` | See [the Border Radius](#the-border-radius) |\r\n| `maxWidth` | `string` | See [the Max Width](#the-max-width) |\r\n| `maxHeight` | `string` | See [the Max Height](#the-max-height) |\r\n| `allowScrollListener` | `boolean` | See [the Page Scroll Listener](https://www.npmjs.com/package/@a11y-ngx/overlay-base#the-page-scroll-listener) in the Base Class library |\r\n| `allowClose` | `boolean` or `OverlayAllowClose` | See [the Directive Close Listeners](#the-directive-close-listeners) |\r\n| `allowTabCycle` | `boolean` | See [the Tab Cycle Listener](#the-directive-tab-cycle-listener) |\r\n| `firstFocusOn` | `'first'` or `'last'` or `undefined` | See [the Directive Focus on Overlay First](#the-directive-focus-on-overlay-first) |\r\n| `forceScheme` | `string` | See [how to Force a Scheme](#how-to-force-a-scheme) |\r\n\r\n#### The Config Input\r\n\r\nIs the given `OverlayCustomConfig` object or `string` that you could pass on for that specific overlay.\r\n\r\n- **Input / Config Property:** `config`.\r\n- **Type:** `OverlayCustomConfig` or `string`.\r\n\r\nThe `object` will contain all the needed properties, while the `string` will be treated as the `selector`, and make a reference for a sub level configuration (previously set in the [customConfig() Method](#the-customconfig-method)).\r\n\r\n> **NOTE:** The `object` can also contain the [`selector` property](#the-config-input-through-an-object), which means that you can set _that_ \"sub level\" configuration inside the object, plus some extra other configs for that instance.\r\n\r\n##### The Config Input Examples\r\n\r\nWhenever you create an overlay, either by using a [directive](#the-overlay-directive), a [component](#the-overlay-component) or the [create service](#the-overlay-create-service), you can pass a [configuration object](#the-config-input-through-an-object) or a [string](#the-config-input-through-a-string) into the `[config]` input.\r\n\r\n###### The Config Input through an Object\r\n\r\nThe object will contain the needed properties for customization. Optionally, if needed, you can also make use of the `selector` property, to define the specific configuration sub set established within [the `customConfig()` method](#the-customconfig-method).\r\n\r\n```typescript\r\nimport { OverlayCustomConfig } from '@a11y-ngx/overlay';\r\n\r\n...\r\n\r\n@ViewChild('overlayTrigger', { static: true }) overlayTrigger: ElementRef;\r\n\r\noverlayConfig: OverlayCustomConfig = {\r\n selector: 'my-custom-component',\r\n trigger: this.overlayTrigger.nativeElement,\r\n position: ['right', 'end'],\r\n arrowSize: 0,\r\n};\r\n```\r\n\r\n```html\r\n\r\n...\r\n```\r\n\r\n###### The Config Input through a String\r\n\r\nWhen a `string` is passed as a config, it is going to be treated as the `selector` that was set within the `config` when [customConfig() Method](#the-customconfig-method) was used, to configure a sub level of overlays that will live under that selector in the DOM.\r\n\r\n```html\r\n...\r\n```\r\n\r\n###### The Config Input through the `OverlayCreateService`\r\n\r\nIs the third parameter for the `createOverlay()` method from the [Overlay Create Service](#the-overlay-create-service).\r\n\r\nYou can follow the examples above, and pass either [an Object](#the-config-input-through-an-object) or [a String](#the-config-input-through-a-string).\r\n\r\n### The Directive Outputs\r\n\r\n| Name | Type | Description |\r\n| :--- | :--- | :---------- |\r\n| `overlayOpen` | `EventEmitter` | Will emit when `show()` method is invoked |\r\n| `overlayClose` | `EventEmitter` | Will emit when `hide()` method is invoked, and right after [the fade timeout](#the-fade-timeout) has completed |\r\n| `overlayToggle` | `EventEmitter` | Will emit values of `'open'` or `'close'`, accordingly |\r\n\r\n### The Directive public Methods, Properties, Getters and Setters\r\n\r\n| Name | Type | Of Type | Description |\r\n| :--- | :--- | :------ | :---------- |\r\n| `nativeElement` | `get` | `HTMLElement` | The host element: `` for the component or the HTML element for the directive |\r\n| `isVisible` | `get` | `boolean` | It means that the host element is reachable within the DOM.
It doesn't mean is \"visually visible\" |\r\n| `isOpaque` | `get` | `boolean` | The Overlay is \"visually visible\", is fully opaque. |\r\n| `borderSize` | `get`/`set` | `number` | See [the Border Size](#the-border-size) |\r\n| `arrowSize` | `get`/`set` | `number` | See [the Arrow Size](#the-arrow-size) |\r\n| `fadeMs` | `get`/`set` | `number` | See [the Fade Timeout](#the-fade-timeout) |\r\n| `fadeDelayMs` | `get`/`set` | `number` | See [the Fade Delay Timeout](#the-fade-delay-timeout) |\r\n| `zIndex` | `get`/`set` | `number` | See [the zIndex](#the-zindex) |\r\n| `setOverlayConfig()` | `method` | `void` | See [how to set the Overlay Config](#the-directive-setoverlayconfig-method) |\r\n| `setStyles()` | `method` | `void` | See [how to set the Directive Styles](#the-directive-setstyles-method) |\r\n| `setCustomSelector()` | `method` | `void` | See [how to set the Directive Custom Selector](#the-directive-setcustomselector-method) |\r\n| `show()` | `method` | `void` | See [the Directive Show method](#the-directive-show-method) |\r\n| `hide()` | `method` | `void` | See [the Directive Hide method](#the-directive-hide-method) |\r\n| `toggle()` | `method` | `void` | See [the Directive Toggle method](#the-directive-toggle-method) |\r\n| `overlayUpdated$` | `property` | `Subject` | To listen to the data when the directive updates the host's position. See [the calculated position (from the Base Class library)](https://www.npmjs.com/package/@a11y-ngx/overlay-base#the-calculated-position) |\r\n| `destroy$` | `property` | `Subject` | To listen to for when the directive gets destroyed |\r\n\r\n#### The Directive `setOverlayConfig()` Method\r\n\r\nServes to set the directive's config.\r\n\r\nAccepts a single parameter `config` of type [`OverlayCustomConfig`](#the-overlay-custom-config).\r\n\r\nIt is executed every time a directive is created and on change life cycle.\r\n\r\n#### The Directive `setStyles()` Method\r\n\r\nServes to set the custom given styles into the host element.\r\n\r\nAccepts a single parameter `theStyles` of type [`OverlayCustomConfig`](#the-overlay-custom-config), which will only process [the properties meant for styling](#the-styles-config).\r\n\r\nIt is executed on the directive's change life cycle, right after [the `setOverlayConfig()` method](#the-directive-setoverlayconfig-method).\r\n\r\n#### The Directive `setCustomSelector()` Method\r\n\r\nTo be used when an instance of a custom component is created extending the directive as a base.\r\n\r\nThis way you can set your custom component's selector so the directive can make use of the Color Scheme service properly.\r\n\r\nAccepts a single parameter `selector` of type `string`.\r\n\r\n#### The Directive `show()` Method\r\n\r\nShows the overlay and sets its position.\r\n\r\nThis means that:\r\n\r\n1. It will replace the `display: none;` for `display: flex;` CSS property:
\r\n This is the first step so the _Base Class_ can have access to the overlay's `DOMRect` data to calculate its current size.\r\n2. It will set focus on the overlay element (if [`allowTabCycle`](#the-directive-tab-cycle-listener) is set to `true`).\r\n3. It will emit `overlayOpen` and `overlayToggle`.\r\n4. It will attach the overlay and listen for changes (window resize and/or scroll) to update its coordinates and/or max sizes.\r\n5. It will start to fade in the host element after _n_ milliseconds (established by [the `fadeDelayMs` property](#the-fade-delay-timeout)).\r\n6. It will push the _calculated position_ into `overlayUpdated$` subject.\r\n\r\n#### The Directive `hide()` Method\r\n\r\nHides the overlay.\r\n\r\nThis means that:\r\n\r\n1. It will fade out the host element.\r\n2. It will detach the overlay.\r\n3. It will set focus back on the trigger element (if [`allowTabCycle`](#the-directive-tab-cycle-listener) is set to `true`) and the trigger is an instance of `HTMLElement` (not a `DOMRect`).\r\n4. After those _n_ milliseconds (established by [the fadeMs property](#the-fade-timeout) and [the `fadeDelayMs` property](#the-fade-delay-timeout)) it will:\r\n 1. Add the `display: none;` CSS property.\r\n 2. Emit `overlayClose` and `overlayToggle`.\r\n\r\n#### The Directive `toggle()` Method\r\n\r\nIt will switch between `show()` or `hide()` methods, based on the `isVisible` getter.\r\n\r\n### The Directive Listeners\r\n\r\nSince the main idea of this library is to help on accessibility matters, for those that can have specific content where the user needs to explore with their keyboards, both [tab cycle](#the-directive-tab-cycle-listener) and [close on escape](#the-directive-close-on-escape-listener) listeners are available.\r\n\r\n#### The Directive Close Listeners\r\n\r\nAllows to set the \"on close\" listeners: **Escape** and/or **Click Outside**.\r\n\r\n- **Input / Config Property:** `allowClose`.\r\n- **Type:** `boolean` or `OverlayAllowClose`.\r\n- **Default:** `true`.\r\n\r\nIf a boolean is passed, then both \"[close on escape](#the-directive-close-on-escape-listener)\" and \"[close on click outside](#the-directive-close-on-click-outside-listener)\" are going to be configured with that value.\r\n\r\nOn the other hand, if the `OverlayAllowClose` type is used, you can find 2 properties to set individually:\r\n\r\n- `escape` of type `boolean`.\r\n- `clickOutside` of type `boolean`.\r\n\r\n> ⚠️ **IMPORTANT:** Be careful about this option, **do not set this to `false` by default**, specially when [`allowTabCycle`](#the-directive-tab-cycle-listener) is set to `true`, otherwise the focus will remain inside the overlay and keyboard **users won't be able to close it**.\r\n>\r\n> This option should be considered when you are providing other ways to close the overlay, such as custom listeners (`mouseleave` or `blur`) or custom buttons, like \"Close\" or \"Confirm & Cancel\".\r\n\r\n##### The Directive Close on Escape Listener\r\n\r\nAllows to close the overlay by pressing the `escape` key, either if the [tab cycle](#the-directive-tab-cycle-listener) is on or off.\r\n\r\n- **Input / Config Property:** `allowClose` or `allowClose.escape`.\r\n- **Type:** `boolean`.\r\n- **Default:** `true`.\r\n\r\n> **NOTE:** The `escape` listener will be attached to different elements according to:\r\n>\r\n> - If `allowTabCycle` is set to `true`, the listener will be in the **overlay** element.\r\n> - If `allowTabCycle` is set to `false`, the listener will be in the **trigger** element.\r\n> - If no trigger element is present (because a [DOMRect was provided instead](#the-service-create-method-using-a-domrect-trigger)), the listener will be in the **document** element.\r\n\r\n##### The Directive Close on Click Outside Listener\r\n\r\nAllows to close the overlay when the user clicks outside of it.\r\n\r\n- **Input / Config Property:** `allowClose` or `allowClose.clickOutside`.\r\n- **Type:** `boolean`.\r\n- **Default:** `true`.\r\n\r\n#### The Directive Tab Cycle Listener\r\n\r\nIf the content has interactive/tabbable elements, it is highly recommended that the focus is set to the overlay and remains within. So, whenever the user uses the `tab` key, the cycle will be among all focusable elements and should not be lost outside.\r\n\r\nThe same way focus is set within the overlay, it will return to the trigger when the overlay closes, either by using the [escape key](#the-directive-close-on-escape-listener) or the [`hide()` method](#the-directive-hide-method) (because you **must implement** another way to close it via keyboard, like a close button).\r\n\r\n- **Dependency:** [Tab Cycle package](https://www.npmjs.com/package/@a11y-ngx/tab-cycle).\r\n- **Input / Config Property:** `allowTabCycle`.\r\n- **Type:** `boolean`.\r\n- **Default:** `true`.\r\n\r\n> **NOTE:** When set to `true`, a set of attributes will be established automatically to the overlay element:\r\n>\r\n> - `tabindex=\"-1\"` (if no value was provided)\r\n> - `role=\"dialog\"`\r\n> - `aria-modal=\"true\"`\r\n>\r\n> This way, screen reader users can have the full and addecuate experience when navigate with their keyboards.\r\n>\r\n> ⚠️ **IMPORTANT:** This feature does not apply if you are, for instance, creating a [context menu](#the-context-menu) since they are navigated using the arrow keys and the `role` should be of type `menu` and `menuitem` along with other aria attributes.\r\n\r\n##### The Directive Focus on Overlay First\r\n\r\nIf `allowTabCycle` is set to `true`, this property will define where the first focus is going to be set.\r\n\r\n- **Input / Config Property:** `firstFocusOn`.\r\n- **Type:** `'first'`, `'last'` or `undefined`.\r\n- **Default:** `undefined`.\r\n\r\nBy default, focus will be set on the overlay element. If is set to `'first'`, focus goes to the first tabbable element; if set to `'last'` then goes to the last tabbable element (or the overlay, if none were found).\r\n\r\n> **Regarding Accessibility:** There has been a big discussion on if the focus should be set on the main container element or the first interactive element.\r\n>\r\n> Most people recommend to set focus on the first interactive element, expecting to be a \"close button\".\r\n>\r\n> Now imagine that you have some explainatory text and _then_ a couple of buttons to \"accept\" or \"cancel\". By setting the focus to the first interactive element (the \"accept\" button in this case), the screen reader users will lost the context of the message, since they are going to be standing at the end of the container.\r\n>\r\n> Please choose wisely if you change this option to `'first'` or `'last'`.\r\n\r\n## The Overlay Component\r\n\r\nThe `OverlayComponent` extends from [the `OverlayDirective` class](#the-overlay-directive).\r\n\r\n- **Selector:** `'a11y-overlay'`.\r\n- **Exported As:** `a11yOverlay`.\r\n\r\nBehind the scenes, this one will take care of using all the styles through the stylesheet.\r\n\r\nThe stylesheet will make use of the values established within [the Config Styles Type](#the-styles-config) for:\r\n\r\n- [`fadeMs`](#the-fade-timeout).\r\n- [`padding`](#the-padding).\r\n- [`shadow`](#the-shadow).\r\n- [`shadowColor`](#the-shadow).\r\n- [`backgroundColor`](#the-background-color).\r\n- [`textColor`](#the-text-color).\r\n- [`borderSize`](#the-border-size).\r\n- [`borderColor`](#the-border-color).\r\n- [`borderRadius`](#the-border-radius).\r\n- [`zIndex`](#the-zindex).\r\n\r\n## The Overlay Arrow Component\r\n\r\n- **Selector:** `'a11y-overlay-arrow'`.\r\n\r\nThis component has no template, it only contains a stylesheet to show an arrow-like shape \"visually attached\" on the overlay, pointing to the trigger.\r\n\r\nThe component will subscribe to the `overlayUpdated$` property from the directive to update the arrow's position.\r\n\r\nThe stylesheet will make use of the values established within [the Config Styles Type](#the-styles-config) for:\r\n\r\n- [`arrowSize`](#the-arrow-size).\r\n- [`backgroundColor`](#the-background-color).\r\n- [`borderSize`](#the-border-size).\r\n- [`borderColor`](#the-border-color).\r\n\r\n### The Arrow Component inside the Directive\r\n\r\nIf you are going to use an overlay directive, instead of a component, and specially if your intention is to use `overflow`, please consider wrapping the content within a new `
` element and apply the overflow to _that_ div, to avoid issues with the arrow.\r\n\r\nSee an example of [the Directive Use](#the-directive-use).\r\n\r\n## The Overlay Create Service\r\n\r\nThis service becomes useful when you want to use a `TemplateRef` content for the overlay.\r\n\r\nIt provides a [method to create the overlay](#the-service-create-method) and a [method to destroy it](#the-service-destroy-method), if needed.\r\n\r\n### The Service Create Method\r\n\r\nThe `createOverlay()` method creates (and returns) an `OverlayComponent` instance and uses the given template as its content. The `` element will be rendered right after the trigger in the DOM (if given) or within a _container_ at the end of the `` (if `DOMRect` was provided).\r\n\r\nAccepts three parameters:\r\n\r\n- `trigger` of type `HTMLElement` or `DOMRect`.\r\n- `content` of type `TemplateRef` or `string`.\r\n- `config` (_optional_) of type [OverlayCustomConfig](#the-config-input-through-an-object) or [string](#the-config-input-through-a-string).\r\n\r\n> **NOTE:** If you need to remove the rendered `` element at any point, you can use [the Overlay Destroy method](#the-service-destroy-method) from the returned component instance.\r\n\r\n#### The Service Create Method using an `HTMLElement` Trigger\r\n\r\n```typescript\r\nimport { OverlayComponent, OverlayCreateService } from '@a11y-ngx/overlay';\r\n\r\n...\r\n\r\n@ViewChild('overlayTrigger') overlayTrigger: ElementRef;\r\n@ViewChild('overlayTemplate') overlayTemplate: TemplateRef;\r\n\r\nprivate myOverlay: OverlayComponent;\r\n\r\nconstructor(private overlayCreateService: OverlayCreateService) {}\r\n\r\ntoggleOverlay(): void {\r\n if (!this.myOverlay) {\r\n this.myOverlay = this.overlayCreateService.createOverlay(\r\n this.overlayTrigger.nativeElement, // trigger\r\n this.overlayTemplate, // content\r\n { // config\r\n position: ['bottom', 'end'],\r\n fadeMs: 500,\r\n });\r\n }\r\n\r\n this.myOverlay.toggle();\r\n}\r\n```\r\n\r\n```html\r\n\r\n...\r\n```\r\n\r\n#### The Service Create Method using a `DOMRect` Trigger\r\n\r\nSince there is no actual `trigger` HTML element, another service will attach the overlay to a _container_ in the ``.\r\n\r\nThese scenarios can be useful for overlays that are not visually attached to _anything_, such as context menus, where only `x` and `y` coordinates (the clicked point) are needed to position the overlay.\r\n\r\n> 📘 **NOTE:** You can see the extended version of the following code in [the Context Menu example](#the-context-menu)\r\n\r\n```typescript\r\n@HostListener('document:contextmenu', ['$event'])\r\n private onContextMenu(event: PointerEvent): void {\r\n event.preventDefault();\r\n\r\n if (!this.myOverlay) {\r\n this.myOverlay = this.overlayCreateService.createOverlay(\r\n new DOMRect(event.x, event.y, 0, 0), // trigger\r\n this.overlayTemplate, // content\r\n '.context-menu' // config's selector\r\n );\r\n }\r\n\r\n this.myOverlay.toggle();\r\n }\r\n```\r\n\r\n### The Service Destroy Method\r\n\r\nThe `destroyOverlay()` method serves the purpose of destroying the rendered `` element from the DOM.\r\n\r\nIt can be invoked from the component instance generated in [the Service Create method](#the-service-create-method).\r\n\r\n```typescript\r\nthis.myOverlay.destroyOverlay();\r\nthis.myOverlay = undefined;\r\n```\r\n\r\n## The Color Schemes\r\n\r\nThis library uses [Color Scheme package](https://www.npmjs.com/package/@a11y-ngx/color-scheme) as a dependency so you can make use of the two basic color schemes: `light` and `dark` (or more).\r\n\r\n### How to Configure the Color Schemes\r\n\r\nYou can establish all the color related stuff for the preset schemes (`light` and `dark`) or any other you may have added when using the `rootConfig()` method.\r\n\r\n- **Config Property:** `colorSchemes`.\r\n- **Properties:**\r\n - `light`.\r\n - `dark`.\r\n - _'code-name'_ (any other).\r\n\r\nLet's say you don't like the default text color for the `light` scheme (`#222`), then you can change it like this:\r\n\r\n```typescript\r\nA11yOverlayModule.rootConfig({\r\n ...\r\n safeSpace: { top: 65, left: 50 },\r\n borderSize: 2,\r\n ...\r\n colorSchemes: {\r\n light: {\r\n textColor: '#000',\r\n },\r\n dark: {...},\r\n 'red-velvet': {...}, // being 'red-velvet' the code-name\r\n },\r\n}),\r\n```\r\n\r\n> **NOTES:**\r\n>\r\n> 1. You can add any other _generic_ style value from the config (not related to color) at the _root_ level of the object provided, as shown for the `borderSize` property.\r\n> 2. If you add a color-related property at the _root_ level, it will be treated as _generic_ and will affect all overlays.\r\n\r\n","readmeFilename":"README.md"}