docs(popover): docs so far

Author: thejackshelton

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

@@ -16,7 +16,7 @@ A window overlaid on either the primary window or another dialog window. Modal c
 
 The modal makes use of the HTML `dialog` element, which is supported in [every major browser](https://caniuse.com/?search=dialog).
 
-> For non-modal UI elements, it is preferred to use [Qwik UI's popover component](../../../docs/headless/popover/) _(in progress)_. In the near future, Qwik's popover component can be applied to the most-semantically-relevant HTML element, including the `<dialog>` element itself for non-modal dialogs.
+> For non-modal UI elements, it is preferred to use [Qwik UI's popover component](../../../docs/headless/popover/). Qwik's popover component can be applied to the most-semantically-relevant HTML element, including the `<dialog>` element itself for non-modal dialogs.
 
 Modals are used when an important choice needs to be made in the application. The rest of the content isn't interactive until a certain action has been performed.
 

apps/website/src/routes/docs/headless/popover/examples/anchor-ref.tsx

@@ -3,20 +3,19 @@ import { Popover, PopoverTrigger } from '@qwik-ui/headless';
 import { usePopover } from '@qwik-ui/headless';
 
 export default component$(() => {
-  const buttonRef = useSignal<HTMLButtonElement>();
   const { showPopover, hidePopover } = usePopover(`anchor-ref-id`);
-  const myPopoverRef = useSignal<HTMLElement>();
+  const triggerRef = useSignal<HTMLButtonElement>();
+  const popoverRef = useSignal<HTMLElement>();
 
   return (
     <>
-      <div>
-        We're using popover target action on the trigger.{' '}
+      <div class="flex flex-col items-center justify-center gap-2">
+        <p>I'm a mini tooltip!</p>
         <PopoverTrigger
-          ref={buttonRef}
+          ref={triggerRef}
           disableClickInitPopover
           onPointerEnter$={() => {
             showPopover();
-            console.log('in pointer!');
           }}
           onPointerLeave$={() => {
             hidePopover();
@@ -25,13 +24,13 @@ export default component$(() => {
           popovertarget="anchor-ref-id"
           class="rounded-md border-2 border-slate-300 bg-slate-800 px-3 py-1 text-white"
         >
-          Popover Trigger
+          Hover over me
         </PopoverTrigger>
       </div>
 
       <Popover
-        anchorRef={buttonRef}
-        popoverRef={myPopoverRef}
+        ref={popoverRef}
+        anchorRef={triggerRef}
         floating={true}
         placement="top"
         gutter={4}

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

@@ -0,0 +1,71 @@
+import { component$, useSignal } from '@builder.io/qwik';
+import {
+  Combobox,
+  ComboboxLabel,
+  ComboboxControl,
+  ComboboxInput,
+  ComboboxTrigger,
+  ComboboxPopover,
+  ComboboxListbox,
+  ComboboxOption,
+  ResolvedOption,
+} from '@qwik-ui/headless';
+
+import './animation.css';
+
+export default component$(() => {
+  const isListboxOpenSig = useSignal(false);
+
+  const animationExample = ['I', 'Float', 'Above', 'Other', 'Content!'];
+
+  return (
+    <Combobox
+      class="w-fit bg-transparent"
+      options={animationExample}
+      filter$={(value: string, options) =>
+        options.filter(({ option }) => {
+          return option.toLowerCase().startsWith(value.toLowerCase());
+        })
+      }
+      bind:isListboxOpenSig={isListboxOpenSig}
+    >
+      <ComboboxLabel class=" mb-2 block font-semibold text-white">
+        I open a floating element!
+      </ComboboxLabel>
+      <ComboboxControl class="relative flex items-center rounded-sm border-[1px] border-slate-400 bg-[#1f2532]">
+        <ComboboxInput
+          class="px-d2 w-fit bg-slate-900 px-2 pr-6 text-white placeholder:text-slate-500"
+          placeholder="Wallaby Rd."
+        />
+        <ComboboxTrigger class="group absolute right-0 h-6 w-6 bg-transparent">
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke-width="2"
+            class="stroke-white transition-transform duration-[450ms] group-aria-expanded:-rotate-180"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          >
+            <polyline points="6 9 12 15 18 9"></polyline>
+          </svg>
+        </ComboboxTrigger>
+      </ComboboxControl>
+      <ComboboxPopover gutter={8}>
+        <ComboboxListbox
+          class={`w-44 rounded-sm border-[1px] border-slate-400 bg-slate-900 px-4 py-2`}
+          optionRenderer$={(option: ResolvedOption, index: number) => (
+            <ComboboxOption
+              key={option.key}
+              class="group rounded-sm border-2 border-transparent px-2 text-white hover:bg-slate-500  aria-disabled:text-slate-600 aria-disabled:hover:bg-slate-700 aria-selected:border-slate-200 aria-selected:bg-slate-500"
+              index={index}
+              resolved={option}
+            >
+              {option.label}
+            </ComboboxOption>
+          )}
+        />
+      </ComboboxPopover>
+    </Combobox>
+  );
+});

apps/website/src/routes/docs/headless/popover/examples/floating-intro.tsx

@@ -0,0 +1,30 @@
+import { component$ } from '@builder.io/qwik';
+import { Popover, usePopover } from '@qwik-ui/headless';
+
+export default component$(() => {
+  const { togglePopover } = usePopover(`programmatic-id`);
+  return (
+    <>
+      <button
+        preventdefault:click
+        class="rounded-md border-2 border-slate-400 bg-slate-800 px-3 py-1 text-white"
+        onKeyDown$={(e) => {
+          if (e.key === 'o') {
+            togglePopover();
+          }
+        }}
+      >
+        Focus me and press the 'o' key!
+      </button>
+      <Popover
+        onBeforeToggle$={() => {
+          console.log('I before toggle!');
+        }}
+        id="programmatic-id"
+        class="shadow-dark-medium rounded-md border-2 border-slate-300 bg-slate-800 px-3 py-1 opacity-0"
+      >
+        I was programmatically opened!
+      </Popover>
+    </>
+  );
+});

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

@@ -19,9 +19,8 @@ A non-modal primitive with overlays that open and close around a DOM element.
     `"Early" access to MDN's native popover API`,
     'Support across all browsers',
     'Resumable / Lazily executes code on interaction',
-    'Top Layer behavior',
-    'Opt-in floating behavior',
-    'Portal polyfill works across meta-frameworks',
+    'UI is placed above everything else.',
+    'stick or float elements to other elements, similar to the upcoming Anchor API.',
   ]}
 />
 
@@ -39,6 +38,8 @@ This is particularly useful for displaying additional information or options wit
 
 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.
 
+Even if a popover is in the HTML Tree, its children will not execute unless resumed.
+
 ## Versatile use cases <span class="ml-2 text-red-400 dark:text-red-400 text-base px-2 bg-red-100 rounded-md shadow-light-low dark:shadow-dark-medium border-b-2 border-[1px] border-red-200 dark:border-red-300">WIP</span>
 
 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.
@@ -119,7 +120,7 @@ A separate declaration is needed to select popovers in all browsers.
 
 ### Cross-browser Animations
 
-Entry and exit animations have often been a frustrating experience. Especially trying to animate between `display: none`, a discrete property.
+Entry and exit animations have often been a frustrating experience in web development. Especially trying to animate between `display: none`, a discrete property.
 
 Until recently, discrete properties were not animatable. Luckily, there's [new properties to CSS](https://developer.chrome.com/blog/entry-exit-animations) that solve this problem.
 
@@ -189,28 +190,60 @@ An auto popover will automatically hide when you click outside of it and typical
 
 On the other hand, a `manual` popover needs to be manually hidden, such as toggling the button or programmatically, and allows for scenarios like nested popovers in menus.
 
-### Popover Methods
+We can add a manual popover by adding the `popover="manual"` prop, or `manual` shorthand.
+
+> Notice that the last opened popover is always above the other!
+
+## Programmatic Behavior
 
-There are two methods for showing and hiding popovers manually in JavaScript. The `showPopover` and `hidePopover` methods.
+<Showcase name="programmatic" />
 
-For example, here is programmatic behavior syncing the popover state with the listbox in the `Combobox` component.
+We can also enable programmatic behavior with popovers. Qwik UI provides several functions you can use to control this behavior.
+
+<AnatomyTable
+  propDescriptors={[
+    {
+      name: 'showPopover()',
+      description: 'Opens the popover.',
+    },
+    {
+      name: 'togglePopover()',
+      description: 'Toggles the popover between the open and closed state.',
+    },
+    {
+      name: 'hidePopover()',
+      description: 'Closes the popover.',
+    },
+  ]}
+/>
+
+We can access them anywhere by importing the `usePopover` hook. We also need to pass in the **popover id or popovertarget string** to usePopover, which will find the popover we intend to perform an action on.
+
+For example, here is programmatic behavior syncing the popover state with the listbox in Qwik UI's `Combobox` component.
 
 ```tsx
-useTask$(function syncPopoverStateTask({ track }) {
+// near the top of the component
+const { showPopover, hidePopover } = usePopover(popoverId);
+
+useTask$(async ({ track }) => {
   track(() => context.isListboxOpenSig.value);
 
-  if (!context.popoverRef.value) {
-    return;
-  }
+  if (isServer) return;
 
-  context.isListboxOpenSig.value
-    ? context.popoverRef.value.showPopover()
-    : context.popoverRef.value.hidePopover();
+  if (context.isListboxOpenSig.value) {
+    showPopover();
+  } else {
+    hidePopover();
+  }
 });
 ```
 
+> In the native spec, these are methods, although we want to ensure the polyfill loads on interaction, rather than page load with a proxy.
+
 ## Floating Behavior
 
+<Showcase name="floating-intro" />
+
 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.
@@ -238,12 +271,12 @@ For the following examples, we'll be using the Combobox component. `ComboboxPopo
 ```tsx
 <Popover
   {...props}
-  manual
   id={popoverId}
+  ref={context.popoverRef}
+  manual
   floating={true}
-  // passing in a custom ref for programmatic behavior
+  // "stick" to the input
   anchorRef={context.inputRef}
-  popoverRef={context.popoverRef}
   class="listbox"
 >
   <Slot />
@@ -256,8 +289,6 @@ To set the default position of the listbox, you can use the `placement` prop. In
 
 <Showcase name="placement" />
 
-The example above sets the `placement` prop to `top`. The default placement is **bottom**.
-
 ### Flip
 
 Allows the listbox to flip its position based on available space. It's enabled by default, but can be disabled by adding `flip={false}` on the listbox.
@@ -301,21 +332,44 @@ If Tailwind is the framework of choice, then styles can be added using the [arbi
 
 > The arbitrary variant can be customized/abstracted even further by [adding a variant](https://tailwindcss.com/docs/plugins#adding-variants) as a plugin in the tailwind config.
 
-## Animations
+### Listbox preset
 
-### The problem
+By default, the popover API comes with built-in styles, including fixed behavior, margin, the list goes on.
 
-Currently, native animation support for the popover API is [not quite there yet](https://open-ui.org/components/popover.research.explainer/#animation-of-popovers). Part of this has to do with the native API managing the popover state and adding the `display: none` declaration.
+There are times when we want to override this behavior. An example being when we want an absolutely positioned listbox.
 
-This declaration is `unanimatable`, meaning you cannot animate to or from display none at this time. With that said, we currently have a way to animate popovers using a clever trick under the hood.
+To do that, we can add the `listbox` class to the popover component.
 
-> There are [new properties to CSS](https://developer.chrome.com/blog/entry-exit-animations) that aim to fix this problem, but regardless we need to be able to support all browsers.
+If you need to override any of the listbox properties, use the following CSS variables:
 
-### Custom animation support
+<AnatomyTable
+  propDescriptors={[
+    {
+      name: 'margin',
+      description: '--listbox-margin',
+    },
+    {
+      name: 'padding',
+      description: '--listbox-padding',
+    },
+    {
+      name: 'border',
+      description: '--listbox-border',
+    },
+    {
+      name: 'overflow',
+      description: '--listbox-overflow',
+    },
+    {
+      name: 'position',
+      description: '--listbox-position',
+    },
+  ]}
+/>
 
-Regardless of native support, animations need support in polyfill browsers too, and so we've provided a way for you to use both `animation` and `transition` declarations in your `Popover` component for **all browsers**.
+> Another option is to use the `!important` syntax to override any of the CSS variable values.
 
-### Animation declarations
+## Animations
 
 <Showcase name="listbox-animation" />
 
@@ -359,8 +413,6 @@ Here's the CSS imported from the example:
 
 ### Transition declarations
 
-<Showcase name="animation" />
-
 Transitions use the same classes for entry and exit animations. Those being `.popover-showing` and `.popover-closing`. They are explained move in the section above.
 
 > The [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) is another native solution that aims to solve animating between states. Support is currently in around **~70%** of browsers.

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

@@ -32,7 +32,7 @@ export const ComboboxPopover = component$(
         id={customPopoverId}
         floating={true}
         anchorRef={context.inputRef}
-        popoverRef={context.popoverRef}
+        ref={context.popoverRef}
         class={['listbox', props.class]}
         manual
       >

packages/kit-headless/src/components/combobox/combobox-popover.tsx

@@ -133,7 +133,7 @@ export const FloatingPopover = component$(
     });
 
     return (
-      <PopoverImpl {...props} popoverRef={popoverRef}>
+      <PopoverImpl {...props} ref={popoverRef}>
         <Slot />
       </PopoverImpl>
     );