Skip to content

Commit

Permalink
docs: improved popover intro
Browse files Browse the repository at this point in the history
  • Loading branch information
thejackshelton committed Apr 22, 2024
1 parent 64c18ce commit 1ff2d38
Show file tree
Hide file tree
Showing 4 changed files with 46 additions and 13 deletions.
14 changes: 14 additions & 0 deletions apps/website/src/routes/docs/headless/popover/examples/basic.tsx
Original file line number Diff line number Diff line change
@@ -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>
</>
);
});
19 changes: 14 additions & 5 deletions apps/website/src/routes/docs/headless/popover/examples/hero.tsx
Original file line number Diff line number Diff line change
@@ -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>
</>
);
Expand Down
14 changes: 12 additions & 2 deletions apps/website/src/routes/docs/headless/popover/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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.

Expand Down
12 changes: 6 additions & 6 deletions packages/kit-headless/src/components/popover/popover.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand All @@ -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();
Expand All @@ -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();
Expand Down Expand Up @@ -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);
Expand All @@ -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);
Expand All @@ -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');
Expand Down

0 comments on commit 1ff2d38

Please sign in to comment.