docs(popover & combobox): docs improvements

thejackshelton · thejackshelton · commit fccf147021d3 · 2023-12-14T20:57:55.000-06:00
diff --git a/apps/website/src/components/api-table/api-table.tsx b/apps/website/src/components/api-table/api-table.tsx
@@ -1,4 +1,5 @@
 import { component$ } from '@builder.io/qwik';
+import { InfoPopup } from '../info-popup/info-popup';
 type APITableProps = {
   propDescriptors: {
     name: string;
@@ -31,41 +32,12 @@ export const APITable = component$(({ propDescriptors }: APITableProps) => {
                   </code>
                 </td>
                 <td class="py-3">
-                  <span class="flex items-center">
+                  <div class="flex items-center gap-2">
                     <code class="rounded-md border border-b-2 px-2">
                       {propDescriptor.type}
                     </code>
-                    {propDescriptor.info && (
-                      // <Popover placement="top">
-                      //   <PopoverContent>
-                      //     <div class="shadow-light-medium bg-qwikui-blue-50 dark:shadow-dark-high text-md  border-qwikui-blue-500 dark:border-qwikui-purple-500 dark:bg-qwikui-purple-100 mb-2 max-w-xs  rounded-lg border-[1px] border-b-2 px-3 py-2 font-[500] text-slate-950 sm:w-max">
-                      //       {propDescriptor?.info}
-                      //     </div>
-                      //   </PopoverContent>
-                      //   <PopoverTrigger>
-                      //     <div class="mx-2 mt-2 rounded-md rounded-xl p-1 hover:bg-slate-500 hover:bg-opacity-50">
-                      //       <svg
-                      //         width="15"
-                      //         height="15"
-                      //         viewBox="0 0 15 15"
-                      //         fill="none"
-                      //         xmlns="http://www.w3.org/2000/svg"
-                      //         aria-hidden="true"
-                      //         focusable="false"
-                      //       >
-                      //         <path
-                      //           d="M7.49991 0.876892C3.84222 0.876892 0.877075 3.84204 0.877075 7.49972C0.877075 11.1574 3.84222 14.1226 7.49991 14.1226C11.1576 14.1226 14.1227 11.1574 14.1227 7.49972C14.1227 3.84204 11.1576 0.876892 7.49991 0.876892ZM1.82707 7.49972C1.82707 4.36671 4.36689 1.82689 7.49991 1.82689C10.6329 1.82689 13.1727 4.36671 13.1727 7.49972C13.1727 10.6327 10.6329 13.1726 7.49991 13.1726C4.36689 13.1726 1.82707 10.6327 1.82707 7.49972ZM8.24992 4.49999C8.24992 4.9142 7.91413 5.24999 7.49992 5.24999C7.08571 5.24999 6.74992 4.9142 6.74992 4.49999C6.74992 4.08577 7.08571 3.74999 7.49992 3.74999C7.91413 3.74999 8.24992 4.08577 8.24992 4.49999ZM6.00003 5.99999H6.50003H7.50003C7.77618 5.99999 8.00003 6.22384 8.00003 6.49999V9.99999H8.50003H9.00003V11H8.50003H7.50003H6.50003H6.00003V9.99999H6.50003H7.00003V6.99999H6.50003H6.00003V5.99999Z"
-                      //           fill="currentColor"
-                      //           fill-rule="evenodd"
-                      //           clip-rule="evenodd"
-                      //         ></path>
-                      //       </svg>
-                      //     </div>{' '}
-                      //   </PopoverTrigger>
-                      // </Popover>
-                      <div>popover placeholder</div>
-                    )}
-                  </span>
+                    {propDescriptor.info && <InfoPopup info={propDescriptor.info} />}
+                  </div>
                 </td>
                 <td class="py-3 align-baseline">
                   <div class="prose prose-sm prose-docs-table px-2">
diff --git a/apps/website/src/components/info-popup/info-popup.tsx b/apps/website/src/components/info-popup/info-popup.tsx
@@ -0,0 +1,73 @@
+import { component$, useId, useSignal, useStyles$ } from '@builder.io/qwik';
+import { Popover, PopoverTrigger } from '@qwik-ui/headless';
+
+type InfoProps = {
+  info: string;
+};
+
+export const InfoPopup = component$((props: InfoProps) => {
+  const popoverTableId = useId();
+  const triggerRef = useSignal<HTMLButtonElement>();
+  const popoverRef = useSignal<HTMLElement>();
+
+  useStyles$(`
+  .fade-info {
+    transition: opacity 0.35s, display 0.35s, overlay 0.35s;
+    transition-behavior: allow-discrete;
+    opacity: 0;
+  }
+  
+  .popover-showing {
+    opacity: 1;
+  }
+  
+  .popover-closing {
+    opacity: 0;
+  }  
+  `);
+
+  return (
+    <>
+      <PopoverTrigger
+        ref={triggerRef}
+        popoverTargetAction="show"
+        popovertarget={popoverTableId}
+        class="flex items-center justify-center"
+      >
+        <div class="rounded-full p-1 hover:bg-slate-300 hover:bg-opacity-50">
+          <svg
+            width="16"
+            height="16"
+            viewBox="0 0 15 15"
+            fill="none"
+            xmlns="http://www.w3.org/2000/svg"
+            aria-hidden="true"
+            focusable="false"
+          >
+            <path
+              d="M7.49991 0.876892C3.84222 0.876892 0.877075 3.84204 0.877075 7.49972C0.877075 11.1574 3.84222 14.1226 7.49991 14.1226C11.1576 14.1226 14.1227 11.1574 14.1227 7.49972C14.1227 3.84204 11.1576 0.876892 7.49991 0.876892ZM1.82707 7.49972C1.82707 4.36671 4.36689 1.82689 7.49991 1.82689C10.6329 1.82689 13.1727 4.36671 13.1727 7.49972C13.1727 10.6327 10.6329 13.1726 7.49991 13.1726C4.36689 13.1726 1.82707 10.6327 1.82707 7.49972ZM8.24992 4.49999C8.24992 4.9142 7.91413 5.24999 7.49992 5.24999C7.08571 5.24999 6.74992 4.9142 6.74992 4.49999C6.74992 4.08577 7.08571 3.74999 7.49992 3.74999C7.91413 3.74999 8.24992 4.08577 8.24992 4.49999ZM6.00003 5.99999H6.50003H7.50003C7.77618 5.99999 8.00003 6.22384 8.00003 6.49999V9.99999H8.50003H9.00003V11H8.50003H7.50003H6.50003H6.00003V9.99999H6.50003H7.00003V6.99999H6.50003H6.00003V5.99999Z"
+              fill="currentColor"
+              fill-rule="evenodd"
+              clip-rule="evenodd"
+            ></path>
+          </svg>
+        </div>
+      </PopoverTrigger>
+
+      <Popover
+        ref={popoverRef}
+        anchorRef={triggerRef}
+        floating={true}
+        flip={false}
+        placement="top"
+        gutter={4}
+        id={popoverTableId}
+        class="fade-info listbox rounded-md bg-transparent"
+      >
+        <div class="shadow-light-medium bg-qwikui-blue-50 dark:shadow-dark-high text-md border-qwikui-blue-500  dark:border-qwikui-purple-500 dark:bg-qwikui-purple-100 bg-primary mb-2 max-w-xs  rounded-lg border-[1px] border-b-2 px-3 py-2 font-[500] text-slate-950 sm:w-max">
+          {props.info}
+        </div>
+      </Popover>
+    </>
+  );
+});
diff --git a/apps/website/src/routes/docs/headless/combobox/index.mdx b/apps/website/src/routes/docs/headless/combobox/index.mdx
@@ -3,6 +3,7 @@ title: Qwik UI | Combobox
 ---
 
 import { statusByComponent } from '~/_state/component-statuses';
+import { FeatureList } from '~/components/feature-list/feature-list';
 
 <StatusBanner status={statusByComponent.headless.Combobox} />
 
@@ -25,14 +26,18 @@ Qwik UI's Combobox implementation follows the [WAI-Aria Combobox specifications]
 
 ## ✨ Features
 
-- Full WAI-Aria compliance
-- Full keyboard navigation
-- Custom Autocomplete behavior
-- Custom filter functionality
-- Controlled or uncontrolled
-- Supports disabled options
-- Custom signal binds
-- Animatable, dynamic, and resumable
+<FeatureList
+  features={[
+    'Full WAI-Aria compliance',
+    'Full keyboard navigation',
+    'Custom Autocomplete behavior',
+    'Custom filter functionality',
+    'Controlled or uncontrolled',
+    'Supports disabled options',
+    'Custom signal binds',
+    'Animatable, dynamic, and resumable',
+  ]}
+/>
 
 <br />
 
@@ -182,18 +187,6 @@ This can get tedious if certain custom behavior needs to be added, or the listbo
 
 To disable this behavior, set `disableOnBlur={true}` on the Input.
 
-## **Configuring the Listbox**
-
-The `ComboboxListbox` component is designed for positioning elements that float and facilitating interactions with them. The listbox is highly configurable, here are some example use cases:
-
-### Placement
-
-To set the default position of the listbox, you can use the `placement` prop. In the example below, we've set placement to top. When the user opens the listbox, it will be above the input.
-
-<Showcase name="placement" />
-
-The default placement is **bottom**.
-
 ## Customizing State Signals
 
 The Combobox component allows you to customize its state signals. This can be useful if you want to control or observe these states externally.
@@ -407,22 +400,9 @@ The Combobox component API provides a set of properties that allow you to custom
   ]}
 />
 
-### ComboboxPortal
+### ComboboxPopover
 
-<APITable
-  propDescriptors={[
-    {
-      name: 'elementToTeleport',
-      type: 'JSXNode',
-      description: 'The children to be rendered inside the portal.',
-    },
-    {
-      name: 'contextIds',
-      type: 'Array<string>',
-      description: 'An array of context ids to be passed to the portal.',
-    },
-  ]}
-/>
+The Combobox Popover is a wrapper of [Qwik UI's popover component](../../../docs/headless/popover/). You can view the full API table at the bottom of the popover page.
 
 ### ComboboxListbox
 
diff --git a/apps/website/src/routes/docs/headless/introduction/index.mdx b/apps/website/src/routes/docs/headless/introduction/index.mdx
@@ -4,6 +4,7 @@ title: Qwik UI | Introduction
 
 import headlessHero from '../../../../../public/images/qwik-ui-headless-hero.webp';
 import { Note } from '~/components/note/note';
+import { FeatureList } from '~/components/feature-list/feature-list';
 import {
   AccordionRoot,
   AccordionItem,
@@ -66,6 +67,8 @@ This approach also encompasses future native APIs. Users of Qwik UI might find t
 
 > For instance, [Qwik UI's popover component](https://github.com/qwikifiers/qwik-ui/pull/445) uses the native Popover API on supported browsers. The Anchor API is also incrementally adoptable.
 
+Thanks to resumability, we do less work because there are less components to execute. With Qwik UI we build on top of that, providing the same functionality with less code needed to prefetch in the first place.
+
 ## Features
 
 ### Unstyled
@@ -94,13 +97,17 @@ Conversely, some packages offer great UX, but fall short when it comes to DX.
 
 One of the benefits of Qwik is its ability to create performant applications without compromising on DX. Our goal is to extend this same balance of performance and ease-of-use to those utilizing Qwik UI components.
 
-Some examples being:
-
-- TypeScript support
-- Custom Signal Binds
-- Automatic entry and exit animations
-- SSR & SSG, SPA, and hybrid support
-- Fine-grained lazy loading
+#### Some examples being:
+
+<FeatureList
+  features={[
+    'TypeScript support',
+    'Custom Signal Binds',
+    'Automatic entry and exit animations across browsers',
+    'Works across environments / microfrontends',
+    'Automatic performance optimization',
+  ]}
+/>
 
 ## Community Driven
 
diff --git a/apps/website/src/routes/docs/headless/modal/index.mdx b/apps/website/src/routes/docs/headless/modal/index.mdx
@@ -7,6 +7,7 @@ import testImage from '../../../../../public/images/test-image.png';
 import { statusByComponent } from '~/_state/component-statuses';
 
 <StatusBanner status={statusByComponent.headless.Modal} />
+import {FeatureList} from '~/components/feature-list/feature-list';
 
 # Modal
 
@@ -31,14 +32,18 @@ Modals are used when an important choice needs to be made in the application. Th
 
 ## ✨ Features
 
-- Follows the WAI ARIA Dialog & Alertdialog design patterns.
-- Managed focus order
-- Scroll locking
-- Closes on escape
-- Toggle backdrop dismiss
-- Animation support
-- Transition support
-- Backdrop animations
+<FeatureList
+  features={[
+    'Follows the WAI ARIA Dialog & Alertdialog design patterns.',
+    'Managed focus order',
+    'Scroll locking',
+    'Closes on escape',
+    'Toggle backdrop dismiss',
+    'Animation support',
+    'Transition support',
+    'Backdrop animations',
+  ]}
+/>
 
 ## Building Blocks
 
diff --git a/apps/website/src/routes/docs/headless/popover/examples/programmatic.tsx b/apps/website/src/routes/docs/headless/popover/examples/programmatic.tsx
@@ -17,9 +17,6 @@ export default component$(() => {
         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"
       >
diff --git a/apps/website/src/routes/docs/headless/popover/index.mdx b/apps/website/src/routes/docs/headless/popover/index.mdx
@@ -5,6 +5,7 @@ title: Qwik UI | Popover
 import { statusByComponent } from '~/_state/component-statuses';
 import { Note } from '~/components/note/note';
 import { FeatureList } from '~/components/feature-list/feature-list';
+import { APITable } from '~/components/api-table/api-table';
 
 <StatusBanner status={statusByComponent.headless.Popover} />
 
@@ -206,14 +207,14 @@ We can also enable programmatic behavior with popovers. Qwik UI provides several
       name: 'showPopover()',
       description: 'Opens the popover.',
     },
-    {
-      name: 'togglePopover()',
-      description: 'Toggles the popover between the open and closed state.',
-    },
     {
       name: 'hidePopover()',
       description: 'Closes the popover.',
     },
+    {
+      name: 'togglePopover()',
+      description: 'Toggles the popover between the open and closed state.',
+    },
   ]}
 />
 
