Merge pull request #691 from thejackshelton/popover-styles

Deprecate listbox class in favor of floating mode default

Author: thejackshelton

.changeset/tough-keys-rest.md

@@ -0,0 +1,5 @@
+---
+'@qwik-ui/headless': patch
+---
+
+refactor: popover listbox class deprecated and set as a default when in floating mode.

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

@@ -35,7 +35,7 @@ export default component$(() => {
         placement="top"
         gutter={4}
         id="anchor-ref-id"
-        class="my-transition listbox rounded-base border-2 border-slate-300 bg-slate-800 !p-4 text-white shadow-md"
+        class="my-transition rounded-base border-2 border-slate-300 bg-slate-800 !p-4 text-white shadow-md"
       >
         I am anchored to the trigger!
       </Popover>

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

@@ -172,7 +172,10 @@ The browser support for these is similar to support of the popover API. That sai
 
 ```css
 .my-transition {
-  transition: opacity 0.5s, display 0.5s, overlay 0.5s;
+  transition:
+    opacity 0.5s,
+    display 0.5s,
+    overlay 0.5s;
 
   /* on new-line so the declaration is valid in all browsers */
   transition-behavior: allow-discrete;
@@ -324,7 +327,6 @@ For the following examples, we'll be using the Combobox component. `ComboboxPopo
   floating={true}
   // "stick" to the input
   anchorRef={context.inputRef}
-  class="listbox"
 >
   <Slot />
 </Popover>
@@ -379,43 +381,17 @@ 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.
 
-### Listbox preset
+### Floating preset
 
-By default, the popover API comes with built-in styles, including fixed behavior, margin, the list goes on.
+By default, the popover API comes with built-in user agent styles, including fixed behavior, margin, the list goes on.
 
-There are times when we want to override this behavior. An example being when we want an absolutely positioned listbox.
+There are times when we want to override this behavior. An example being when we want floating behavior.
 
-To do that, we can add the `listbox` class to the popover component.
+Qwik UI strips the following styles when in floating mode:
 
-If you need to override any of the listbox properties, use the following CSS variables:
+<CodeSnippet name="floating.css" />
 
-<AnatomyTable
-  firstColumnLabel="Property"
-  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',
-    },
-  ]}
-/>
-
-> Another option is to use the `!important` syntax to override any of the CSS variable values.
+We put it under an `@layer` so that it can be easily overridden when adding your own styles.
 
 ## Animations
 

apps/website/src/routes/docs/headless/popover/snippets/floating.css

@@ -0,0 +1,9 @@
+@layer qwik-ui {
+  [data-floating] {
+    margin: unset;
+    padding: unset;
+    border: unset;
+    overflow: unset;
+    position: absolute;
+  }
+}

packages/kit-headless/src/components/popover/popover.css

@@ -10,17 +10,13 @@
   display: block !important;
 }
 
-/* Popover Presets: TODO figure out specificity to make this easier for user to override */
-.listbox {
-  --listbox-margin: unset;
-  --listbox-padding: unset;
-  --listbox-border: unset;
-  --listbox-overflow: unset;
-  --listbox-position: absolute;
-
-  margin: var(--listbox-margin);
-  padding: var(--listbox-padding);
-  border: var(--listbox-border);
-  overflow: var(--listbox-overflow);
-  position: var(--listbox-position);
+/* Strips the user agent styles from the popover when in floating mode */
+@layer qwik-ui {
+  [data-floating] {
+    margin: unset;
+    padding: unset;
+    border: unset;
+    overflow: unset;
+    position: absolute;
+  }
 }

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

@@ -18,7 +18,7 @@ export const Popover = component$<PopoverProps>((props) => {
     }
 
     return (
-      <FloatingPopover ref={ref} anchorRef={anchorRef} {...rest}>
+      <FloatingPopover data-floating ref={ref} anchorRef={anchorRef} {...rest}>
         <Slot />
       </FloatingPopover>
     );