docs: improved popover intro

Author: thejackshelton

apps/website/src/routes/docs/headless/popover/examples/basic.tsx

@@ -0,0 +1,14 @@
+import { component$ } from '@builder.io/qwik';
+import { Popover, PopoverTrigger } from '@qwik-ui/headless';
+export default component$(() => {
+  return (
+    <>
+      <PopoverTrigger popovertarget="hero-id" class="popover-trigger">
+        Popover Trigger
+      </PopoverTrigger>
+      <Popover id="hero-id" class="popover">
+        My Hero!
+      </Popover>
+    </>
+  );
+});

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

@@ -1,13 +1,22 @@
-import { component$ } from '@builder.io/qwik';
+import { component$, useSignal } from '@builder.io/qwik';
 import { Popover, PopoverTrigger } from '@qwik-ui/headless';
+
 export default component$(() => {
+  const triggerRef = useSignal<HTMLButtonElement>();
+
   return (
     <>
-      <PopoverTrigger popovertarget="hero-id" class="popover-trigger">
-        Popover Trigger
+      <PopoverTrigger ref={triggerRef} popovertarget="popover-id" class="popover-trigger">
+        Click me
       </PopoverTrigger>
-      <Popover id="hero-id" class="popover">
-        My Hero!
+      <Popover
+        anchorRef={triggerRef}
+        floating={true}
+        gutter={4}
+        id="popover-id"
+        class="popover"
+      >
+        I am anchored to the popover trigger!
       </Popover>
     </>
   );

apps/website/src/routes/docs/headless/popover/index.mdx

@@ -23,9 +23,17 @@ A non-modal primitive with overlays that open and close around a DOM element.
   ]}
 />
 
+<Note status="warning">
+  You are about to see a fixed scrolling popover. Yes, this behavior is intended. It is
+  part of the native popover API! If you want to anchor items, there is a floating section
+  that covers this behavior.
+</Note>
+
+<Showcase name="basic" />
+
 The Qwik UI Popover component is designed to align with the [HTML Popover API Specification](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API). As of now, native support for this API is around `82.5%`, and in almost every browser.
 
-To ensure consistent behavior across all browsers, Qwik UI provides a `polyfill` for browser versions that do not support the API natively.
+To ensure consistent behavior across all browsers, Qwik UI provides a `polyfill` with feature parity for browser versions that do not support the API natively.
 
 <div class="flex flex-col gap-2">
   <div>
@@ -296,7 +304,9 @@ useTask$(async ({ track }) => {
 
 To use the popover API with floating elements, you can add the `floating={true}` prop to the Popover component. This API enables the use of JavaScript to dynamically position the listbox using the `top` & `left` absolute properties.
 
-> Enabling the `floating={true}` property will introduce a slight increase in code size, as we currently utilize JavaScript to implement floating items. We've strived to keep it as minimal as possible, but powerful in building complex components in anticipation of the forthcoming anchor API.
+Enabling the `floating={true}` property will introduce a slight increase in code size, as we currently utilize JavaScript to implement floating items. We've strived to keep it as minimal as possible, but powerful in building complex components.
+
+> Once the native anchor API is available in all browsers, you can remove the floating prop and use CSS instead! Smaller bundle size for the win!
 
 To float an element, it must have an anchored element to latch onto. This can be done with the `anchorRef` prop.
 

packages/kit-headless/src/components/popover/popover.test.ts

@@ -12,7 +12,7 @@ async function setup(page: Page, exampleName: string) {
 }
 
 test('@Visual diff', async ({ page }) => {
-  const { driver: d } = await setup(page, 'hero');
+  const { driver: d } = await setup(page, 'basic');
   await expect(page).toHaveScreenshot('closed popover.png');
 
   await d.getTrigger().click();
@@ -24,7 +24,7 @@ test.describe('Mouse Behavior', () => {
   test(`GIVEN a closed popover
         WHEN clicking on the trigger
         THEN the popover should be opened `, async ({ page }) => {
-    const { driver: d } = await setup(page, 'hero');
+    const { driver: d } = await setup(page, 'basic');
     await expect(d.getPopover()).toBeHidden();
 
     await d.getTrigger().click();
@@ -35,7 +35,7 @@ test.describe('Mouse Behavior', () => {
   test(`GIVEN an open popover
         WHEN clicking elsewhere on the page
         THEN the popover should close`, async ({ page }) => {
-    const { driver: d } = await setup(page, 'hero');
+    const { driver: d } = await setup(page, 'basic');
 
     await expect(d.getPopover()).toBeHidden();
     await d.getTrigger().click();
@@ -188,7 +188,7 @@ test.describe('Keyboard Behavior', () => {
     test(`GIVEN a closed popover
           WHEN focusing on the button and pressing the '${key}' key
           THEN the popover should open`, async ({ page }) => {
-      const { driver: d } = await setup(page, 'hero');
+      const { driver: d } = await setup(page, 'basic');
       await expect(d.getPopover()).toBeHidden();
 
       await d.getTrigger().press(key);
@@ -198,7 +198,7 @@ test.describe('Keyboard Behavior', () => {
     test(`GIVEN an open popover
           WHEN focusing on the button and pressing the '${key}' key
           THEN the popover should close`, async ({ page }) => {
-      const { driver: d } = await setup(page, 'hero');
+      const { driver: d } = await setup(page, 'basic');
 
       // Open the popover
       await d.openPopover(key);
@@ -211,7 +211,7 @@ test.describe('Keyboard Behavior', () => {
   test(`GIVEN an open popover
         WHEN focusing on the button and pressing the 'Escape' key
         THEN the popover should close and the trigger be focused`, async ({ page }) => {
-    const { driver: d } = await setup(page, 'hero');
+    const { driver: d } = await setup(page, 'basic');
 
     // Open the popover
     await d.openPopover('Enter');