Version 5.0.13
This commit is contained in:
Neo committed
1 parent
b89858b2ff
commit
5efe744c5f
1407 files changed
+69690
-30177
No files matched your search
@@ -0,0 +1,193 @@
|
||||
# Popover Attribute Polyfill
|
||||
|
||||
[](https://github.com/oddbird/popover-polyfill/actions/workflows/test.yml) [](https://badge.fury.io/js/@oddbird%2Fpopover-polyfill) [](https://app.netlify.com/sites/popover-polyfill/deploys)
|
||||
|
||||
- [Demo](https://popover.oddbird.net/)
|
||||
- [Explainer](https://open-ui.org/components/popover.research.explainer/)
|
||||
|
||||
This polyfills the HTML `popover` attribute and
|
||||
`showPopover`/`hidePopover`/`togglePopover` methods onto HTMLElement, as well as
|
||||
the `popovertarget` and `popovertargetaction` attributes on Button elements.
|
||||
|
||||
## Polyfill Installation
|
||||
|
||||
### Download a copy
|
||||
|
||||
The simplest, recommended way to install the polyfill is to copy it into your
|
||||
project.
|
||||
|
||||
Download `popover.js` (or `popover.min.js`) [from
|
||||
unpkg.com](https://unpkg.com/browse/@oddbird/popover-polyfill/dist/) and add it
|
||||
to the appropriate directory in your project. Then, include it where necessary
|
||||
with a `<script>` tag:
|
||||
|
||||
```html
|
||||
<script src="/path/to/popover.min.js" type="module"></script>
|
||||
```
|
||||
|
||||
Or without [JavaScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules):
|
||||
|
||||
```html
|
||||
<script src="/path/to/popover.iife.min.js"></script>
|
||||
```
|
||||
|
||||
Note that the JS will inject CSS styles into your document (or ShadowRoot).
|
||||
|
||||
### With npm
|
||||
|
||||
For more advanced configuration, you can install with
|
||||
[npm](https://www.npmjs.com/):
|
||||
|
||||
```sh
|
||||
npm install @oddbird/popover-polyfill
|
||||
```
|
||||
|
||||
After installing, you’ll need to use appropriate tooling to use
|
||||
`node_modules/@oddbird/popover-polyfill/dist/popover.js`.
|
||||
|
||||
For most tooling such as Vite, Webpack, and Parcel, that will look like this:
|
||||
|
||||
```js
|
||||
import '@oddbird/popover-polyfill';
|
||||
```
|
||||
|
||||
If you want to manually apply the polyfill, you can instead import the
|
||||
`isSupported` and `apply` functions directly from
|
||||
`node_modules/@oddbird/popover-polyfill/dist/popover-fn.js` file.
|
||||
|
||||
With most tooling:
|
||||
|
||||
```js
|
||||
import { apply, isSupported } from '@oddbird/popover-polyfill/fn';
|
||||
```
|
||||
|
||||
Or in CommonJS environments:
|
||||
|
||||
```js
|
||||
const { apply, isSupported } = require('@oddbird/popover-polyfill/fn');
|
||||
```
|
||||
|
||||
An `isPolyfilled` function is also available, to detect if the Popover methods
|
||||
have been polyfilled:
|
||||
|
||||
```js
|
||||
import { isPolyfilled } from '@oddbird/popover-polyfill/fn';
|
||||
```
|
||||
|
||||
### Via CDN
|
||||
|
||||
For prototyping or testing, you can use the npm package via a Content Delivery
|
||||
Network. Avoid using JavaScript CDNs in production, for [many good
|
||||
reasons](https://blog.wesleyac.com/posts/why-not-javascript-cdn) such as
|
||||
performance and robustness.
|
||||
|
||||
```html
|
||||
<script
|
||||
src="https://cdn.jsdelivr.net/npm/@oddbird/popover-polyfill@latest"
|
||||
crossorigin="anonymous"
|
||||
defer
|
||||
></script>
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
After installation the polyfill will automatically add the correct methods and
|
||||
attributes to the HTMLElement class.
|
||||
|
||||
## Caveats
|
||||
|
||||
This polyfill is not a perfect replacement for the native behavior; there are
|
||||
some caveats which will need accommodations:
|
||||
|
||||
- A native `popover` has a `:popover-open` pseudo selector when in the open
|
||||
state. Pseudo selectors cannot be polyfilled within CSS, and so instead the
|
||||
polyfill will add the `.\:popover-open` CSS class to any open popover. In
|
||||
other words a popover in the open state will have `class=":popover-open"`. In
|
||||
CSS the `:` character must be escaped with a backslash.
|
||||
|
||||
- The `:popover-open` selector within JavaScript methods has been polyfilled,
|
||||
so both `.querySelector(':popover-open')` _and_
|
||||
`.querySelector('.\:popover-open')` will work to select the same element.
|
||||
`matches` and `closest` have also been patched, so
|
||||
`.matches(':popover-open')` will work the same as
|
||||
`.matches('.\:popover-open')`.
|
||||
|
||||
- Using native `:popover-open` in CSS that does not support native `popover`
|
||||
results in an invalid selector, and so the entire declaration is thrown
|
||||
away. This is important because if you intend to style a popover using
|
||||
`.\:popover-open` it will need to be a separate declaration. For example,
|
||||
`[popover]:popover-open, [popover].\:popover-open` will not work.
|
||||
|
||||
- Native `popover` elements use the `:top-layer` pseudo element which gets
|
||||
placed above all other elements on the page, regardless of overflow or
|
||||
z-index. This is not possible to polyfill, and so this library simply sets a
|
||||
really high `z-index`. This means if a popover is within an element that has
|
||||
`overflow:` or `position:` CSS, then there will be visual differences between
|
||||
the polyfill and the native behavior.
|
||||
|
||||
- Native _invokers_ (that is, buttons or inputs using the `popovertarget`
|
||||
attribute) on `popover=auto` will render in the accessibility tree as elements
|
||||
with `expanded`. The only way to do this in the polyfill is setting the
|
||||
`aria-expanded` attribute on those elements. This _may_ impact mutation
|
||||
observers or frameworks which do DOM diffing, or it may interfere with other
|
||||
code which sets `aria-expanded` on elements.
|
||||
|
||||
- The polyfill uses `adoptedStyleSheets` to inject CSS onto the page (and each
|
||||
Shadow DOM). If it can't use that it'll generate a `<style>` tag instead. This
|
||||
means you may see a `<style>` tag you didn't put there, and this _may_ impact
|
||||
mutation observers or frameworks.
|
||||
|
||||
- For browsers which don't support `adoptedStyleSheets` on Shadow Roots, if
|
||||
you are building a ShadowRoot by setting `.innerHTML`, you'll remove the
|
||||
StyleSheet. Either polyfill `adoptedStyleSheets` or call
|
||||
`injectStyles(myShadow)` to add the styles back in.
|
||||
|
||||
- Similarly, if you're using Declarative ShadowDOM or otherwise creating a
|
||||
shadow root without calling `attachShadow`/`attachInternals`, then the
|
||||
polyfill won't inject the styles (because it can't reference the
|
||||
`shadowRoot`). You'll need to manually inject the styles yourself with
|
||||
`injectStyles(myShadow)`.
|
||||
|
||||
- As a stylesheet is injected into the main document, if your host element is
|
||||
a popover, styling with `:host` gets tricky beause `:host` styles always
|
||||
take lower precedence than the main document styles. This is a limitation
|
||||
of CSS and there's not a reasonable workaround. The best workaround for
|
||||
now is to add `!important` to conflicting properties in your `:host` rule.
|
||||
See [#147](https://github.com/oddbird/popover-polyfill/issues/147) for more.
|
||||
|
||||
- Given that the CSS is injected using JavaScript, you may find that you
|
||||
temporarily see popovers as open while the JS is loading. To work around
|
||||
this, you can add the following CSS to your project:
|
||||
|
||||
```css
|
||||
@supports not selector(:popover-open) {
|
||||
[popover]:not(.\:popover-open) {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- When supported, the polyfill creates a cascade layer named `popover-polyfill`.
|
||||
If your styles are not in layers then this should have no impact. If your
|
||||
styles do use layers, you'll need to ensure the polyfill layer is declared
|
||||
first. (e.g. `@layer popover-polyfill, other, layers;`)
|
||||
|
||||
- The polyfill will not work in browsers with partial popover support enabled,
|
||||
and will also not attempt to make experimental support match the final spec.
|
||||
|
||||
## Contributing
|
||||
|
||||
Visit our [contribution guidelines](https://github.com/oddbird/popover-polyfill/blob/main/CONTRIBUTING.md).
|
||||
|
||||
## Sponsor OddBird's OSS Work
|
||||
|
||||
At OddBird, we love contributing to the languages & tools developers rely on.
|
||||
We're currently working on polyfills
|
||||
for new Popover & Anchor Positioning functionality,
|
||||
as well as CSS specifications for functions, mixins, and responsive typography.
|
||||
Help us keep this work sustainable
|
||||
and centered on your needs as a developer!
|
||||
We display sponsor logos and avatars
|
||||
on our [website](https://www.oddbird.net/polyfill/#open-source-sponsors).
|
||||
|
||||
[Sponsor OddBird's OSS Work](https://opencollective.com/oddbird-open-source)
|
||||
Reference in new issue
Block a user