diff --git a/apps/website/src/routes/docs/headless/popover/examples/basic.tsx b/apps/website/src/routes/docs/headless/popover/examples/basic.tsx new file mode 100644 index 000000000..dedb43a8e --- /dev/null +++ b/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 ( + <> + + Popover Trigger + + + My Hero! + + + ); +}); diff --git a/apps/website/src/routes/docs/headless/popover/examples/hero.tsx b/apps/website/src/routes/docs/headless/popover/examples/hero.tsx index dedb43a8e..1571e4f1d 100644 --- a/apps/website/src/routes/docs/headless/popover/examples/hero.tsx +++ b/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(); + return ( <> - - Popover Trigger + + Click me - - My Hero! + + I am anchored to the popover trigger! ); diff --git a/apps/website/src/routes/docs/headless/popover/index.mdx b/apps/website/src/routes/docs/headless/popover/index.mdx index f745e65e4..b7f4badae 100644 --- a/apps/website/src/routes/docs/headless/popover/index.mdx +++ b/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. ]} /> + + 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. + + + + 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.
@@ -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. diff --git a/packages/kit-headless/src/components/popover/popover.test.ts b/packages/kit-headless/src/components/popover/popover.test.ts index 06ab91b10..f5485ad91 100644 --- a/packages/kit-headless/src/components/popover/popover.test.ts +++ b/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');