fix(popover): fix style issue, users can add styles

Author: thejackshelton

apps/website/src/routes/docs/headless/(components)/popover/examples/hero.css

@@ -1,14 +1,21 @@
 import { component$ } from '@builder.io/qwik';
 import { Popover } from '@qwik-ui/headless';
-import './hero.css';
 
 export default component$(() => {
- /* same as tailwind slate */
-
  return (
  <>
- <button popovertarget="example-id">Open Popover!</button>
- <Popover id="example-id">I'm on top of everything!</Popover>
+ <button
+ popovertarget="example-id"
+ class="rounded-md border-2 border-slate-300 bg-slate-800 px-3 py-1 text-white"
+ >
+ Popover Trigger
+ </button>
+ <Popover
+ id="example-id"
+ class="shadow-dark-medium py- rounded-md border-2 border-slate-300 bg-slate-800 px-3 py-1"
+ >
+ Popover
+ </Popover>
  </>
  );
 });

apps/website/src/routes/docs/headless/(components)/popover/examples/hero.tsx

@@ -28,15 +28,13 @@ A popover is a **non-modal** UI element that creates overlays around a DOM eleme
 
 This is particularly useful for displaying additional information or options without navigating away from the current context. It is also a **native replacement for [portals](https://qwik.builder.io/docs/cookbook/portal/#portal)**, which are commonly used in other JavaScript frameworks. 
 
-> A common use case for a popover, is preventing overflow issues within your UI. The popover API guarantees that your content remains above the rest of the page.
+> An example use case for a popover, is preventing overflow issues within your UI. The popover API guarantees that your content remains above the rest of the page.
 
-Most importantly, this API is a foundation for other headless components.
+Most importantly, this API is a foundation for other headless components. Qwik UI is one of the first *(if not the first)* headless libraries to align with the specification. The content inside of Qwik UI popovers are also natively resumable.
 
-## Example use cases
+## Versatile Use Cases
 
-Here are a couple of example components where the Popover API can be used. Including other parts of Qwik UI headless. Throughout the part of the documentation, we will show the Combobox being used as an example.
-
-The content inside of Qwik UI popovers are resumable and built with Qwik in mind.
+Here are a couple of example components where the Popover API can be used. Including other parts of Qwik UI headless. Throughout the documentation, we will show the Combobox being used as an example.
 
  <AnatomyTable
  propDescriptors={[
@@ -75,3 +73,10 @@ The content inside of Qwik UI popovers are resumable and built with Qwik in mind
  ]}
 />
 
+## Caveats
+
+1. The polyfill for the native popover's `:popover-open` pseudo selector uses the `.popover-open` CSS class instead. This class is added to any open popover. With that said, both can be selected using the native way.
+
+2. Styling a popover using .popover-open needs a separate declaration. Using :popover-open in CSS that doesn't support native popover will result in an invalid selector.
+
+3. For **native invokers** (buttons or inputs using the popovertarget attribute) on `popover=auto`, the polyfill sets the `aria-expanded` attribute to render them in the accessibility tree as elements with expanded.

apps/website/src/routes/docs/headless/(components)/popover/index.mdx

@@ -41,11 +41,11 @@ export const loadPolyfill$ = $(async () => {
  import('@oddbird/popover-polyfill'),
  import('@oddbird/popover-polyfill/dist/popover.css?inline'),
  ]);
- // Inject the polyfill CSS into head
+ // Inject the polyfill CSS into head BEFORE everything else so that users can override it without important or inline
  const styleNode = document.createElement('style');
  styleNode.setAttribute('data-qwik-ui-popover-polyfill', '');
  styleNode.textContent = css;
- document.head.appendChild(styleNode);
+ document.head.insertBefore(styleNode, document.head.firstChild);
 });
 
 // This component is a polyfill for the popover API
@@ -147,7 +147,7 @@ export const PopoverImpl = component$<PopoverImplProps>((props) => {
  <>
  {isServer && <div data-qui-popover-pf />}
  <div
- popover={props.popover}
+ popover={props.popover === 'manual' ? 'manual' : 'auto'}
  class={[props.preset, props.class]}
  {...props}
  ref={childRef}