refactor(combobox): resolve options at start

Author: wmertens

apps/website/src/routes/_components/router-head/router-head.tsx

@@ -45,16 +45,16 @@ export const RouterHead = component$(() => {
       <meta name="twitter:site" content="@QwikDev" />
       <meta name="twitter:title" content="Qwik" />
 
-      {head.meta.map((m) => (
-        <meta {...m} />
+      {head.meta.map((m, i) => (
+        <meta key={i} {...m} />
       ))}
 
-      {head.links.map((l) => (
-        <link {...l} />
+      {head.links.map((l, i) => (
+        <link key={i} {...l} />
       ))}
 
-      {head.styles.map((s) => (
-        <style {...s.props} dangerouslySetInnerHTML={s.style} />
+      {head.styles.map((s, i) => (
+        <style key={i} {...s.props} dangerouslySetInnerHTML={s.style} />
       ))}
 
       <CSSThemeScript />

apps/website/src/routes/docs.css

@@ -43,7 +43,7 @@
     }
 
     blockquote {
-      @apply bg-[#BFDBFE] dark:bg-[#312E81] p-4 border-l-[3px] dark:border-[#F3F3F3] border-[#333333] rounded-sm my-4;
+      @apply bg-[#BFDBFE] dark:bg-[#312E81] p-4 lg:p-6 dark:border-[#F3F3F3] border-[#333333] rounded-xl my-4;
     }
 
     ul {

apps/website/src/routes/docs/headless/(components)/combobox/examples.tsx

@@ -1,4 +1,4 @@
-import { $, component$, Slot, useSignal } from '@builder.io/qwik';
+import { component$, Slot } from '@builder.io/qwik';
 import {
   Combobox,
   ComboboxControl,
@@ -9,7 +9,10 @@ import {
   ComboboxTrigger,
 } from '@qwik-ui/headless';
 
-import { ComboboxOption } from '../../../../../../../../packages/kit-headless/src/components/combobox';
+import {
+  ComboboxOption,
+  type ResolvedOption,
+} from '../../../../../../../../packages/kit-headless/src/components/combobox';
 
 import { PreviewCodeExample } from '../../../_components/preview-code-example/preview-code-example';
 
@@ -46,27 +49,25 @@ const objectExample: Array<Trainer> = [
 ];
 
 export const HeroExample = component$(() => {
-  const objectExampleSig = useSignal(objectExample);
-
   return (
     <>
       <PreviewCodeExample>
         <div class="flex flex-col gap-4" q:slot="actualComponent">
-          <Combobox
-            options={objectExampleSig.value}
+          <Combobox<Trainer>
+            options={objectExample}
             optionValueKey="testValue"
             optionLabelKey="testLabel"
             optionDisabledKey="disabled"
-            optionComponent$={(option: Trainer, key: number, index: number) => (
+            renderOption$={(resolved, index: number) => (
               <ComboboxOption
-                key={key}
+                key={resolved.key}
+                resolved={resolved}
                 index={index}
-                option={option}
-                style={option.disabled ? { color: 'gray' } : {}}
+                style={resolved.disabled ? { color: 'gray' } : {}}
                 class="rounded-sm px-2 hover:bg-[#496080] aria-selected:bg-[#496080]  border-2 border-transparent aria-selected:border-[#abbbce] group"
               >
                 <span class="block group-aria-selected:translate-x-[3px] transition-transform duration-350">
-                  {option.testLabel}
+                  {resolved.option.testLabel}
                 </span>
               </ComboboxOption>
             )}
@@ -95,7 +96,11 @@ export const HeroExample = component$(() => {
               </ComboboxTrigger>
             </ComboboxControl>
             <ComboboxPortal>
-              <ComboboxListbox class="text-white w-44 bg-[#1f2532] px-4 py-2 rounded-sm border-[#7d95b3] border-[1px]" />
+              <ComboboxListbox
+                position="bottom"
+                gap={8}
+                class="text-white w-44 bg-[#1f2532] px-4 py-2 rounded-sm border-[#7d95b3] border-[1px]"
+              />
             </ComboboxPortal>
           </Combobox>
         </div>
@@ -126,58 +131,60 @@ export const StringCombobox = component$(() => {
     'Cucumber',
   ];
 
-  const fruitsSig = useSignal(fruits);
-
   return (
     <PreviewCodeExample>
-      <div class="flex flex-col gap-4" q:slot="actualComponent">
-        <div>
+      <div class="flex flex-col items-center gap-4 p-4" q:slot="actualComponent">
+        <div class=" text-left">
           This uses a custom filter to only filter from the beginning of the options.
         </div>
-        <Combobox
-          options={fruitsSig.value}
-          defaultLabel="Currant"
-          filter$={(value: string, options) =>
-            options.filter(({ option }) => {
-              return option.toLowerCase().startsWith(value.toLowerCase());
-            })
-          }
-          optionComponent$={$((option: string, index: number) => (
-            <ComboboxOption
-              class="rounded-sm px-2 hover:bg-[#496080] aria-selected:bg-[#496080]  border-2 border-transparent aria-selected:border-[#abbbce] group"
-              index={index}
-              option={option}
-            >
-              {option}
-            </ComboboxOption>
-          ))}
-        >
-          <ComboboxLabel class=" font-semibold dark:text-white text-[#333333]">
-            Fruits 🍓
-          </ComboboxLabel>
-          <ComboboxControl class="bg-[#1f2532] flex items-center rounded-sm border-[#7d95b3] border-[1px] relative">
-            <ComboboxInput
-              class="px-2 w-44 bg-inherit px-d2 pr-6 text-white"
-              placeholder="Papaya"
-            />
-            <ComboboxTrigger class="w-6 h-6 group absolute right-0">
-              <svg
-                xmlns="http://www.w3.org/2000/svg"
-                viewBox="0 0 24 24"
-                fill="none"
-                class="stroke-white group-aria-expanded:-rotate-180 transition-transform duration-[450ms]"
-                stroke-linecap="round"
-                stroke-width="2"
-                stroke-linejoin="round"
+        <div>
+          <Combobox
+            class="w-fit"
+            options={fruits}
+            defaultLabel="Currant"
+            filter$={(value: string, options) =>
+              options.filter(({ option }) => {
+                return option.toLowerCase().startsWith(value.toLowerCase());
+              })
+            }
+            renderOption$={(resolved: ResolvedOption, index: number) => (
+              <ComboboxOption
+                key={resolved.key}
+                class="rounded-sm px-2 hover:bg-[#496080] aria-selected:bg-[#496080]  border-2 border-transparent aria-selected:border-[#abbbce] group"
+                index={index}
+                resolved={resolved}
               >
-                <polyline points="6 9 12 15 18 9"></polyline>
-              </svg>
-            </ComboboxTrigger>
-          </ComboboxControl>
-          <ComboboxPortal>
-            <ComboboxListbox class="text-white w-44 bg-[#1f2532] px-4 py-2 rounded-sm border-[#7d95b3] border-[1px]" />
-          </ComboboxPortal>
-        </Combobox>
+                {resolved.label}
+              </ComboboxOption>
+            )}
+          >
+            <ComboboxLabel class=" font-semibold dark:text-white text-[#333333]">
+              Fruits 🍓
+            </ComboboxLabel>
+            <ComboboxControl class="bg-[#1f2532] flex items-center rounded-sm border-[#7d95b3] border-[1px] relative">
+              <ComboboxInput
+                class="px-2 w-44 bg-inherit px-d2 pr-6 text-white"
+                placeholder="Papaya"
+              />
+              <ComboboxTrigger class="w-6 h-6 group absolute right-0">
+                <svg
+                  xmlns="http://www.w3.org/2000/svg"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  class="stroke-white group-aria-expanded:-rotate-180 transition-transform duration-[450ms]"
+                  stroke-linecap="round"
+                  stroke-width="2"
+                  stroke-linejoin="round"
+                >
+                  <polyline points="6 9 12 15 18 9"></polyline>
+                </svg>
+              </ComboboxTrigger>
+            </ComboboxControl>
+            <ComboboxPortal>
+              <ComboboxListbox class="text-white w-44 bg-[#1f2532] px-4 py-2 rounded-sm border-[#7d95b3] border-[1px]" />
+            </ComboboxPortal>
+          </Combobox>
+        </div>
       </div>
 
       <div q:slot="codeExample">
@@ -189,7 +196,7 @@ export const StringCombobox = component$(() => {
 
 // Using context example.
 
-import { createContextId, useContextProvider, useContext } from '@builder.io/qwik';
+import { createContextId, useContext, useContextProvider } from '@builder.io/qwik';
 
 // Create a context ID
 export const AnimalContext = createContextId<string[]>('animal-context');
@@ -204,24 +211,23 @@ export const ParentComponent = component$(() => {
 
 export const ContextExample = component$(() => {
   const animals = useContext(AnimalContext);
-  const animalsSig = useSignal(animals);
 
   return (
     <PreviewCodeExample>
       <div class="flex flex-col gap-4" q:slot="actualComponent">
         <Combobox
-          options={animalsSig.value}
-          optionComponent$={$((option: string, index: number) => (
+          options={animals}
+          renderOption$={(resolved: ResolvedOption, index: number) => (
             <ComboboxOption
               index={index}
-              option={option}
+              resolved={resolved}
               class="rounded-sm px-2 hover:bg-[#496080] aria-selected:bg-[#496080]  border-2 border-transparent aria-selected:border-[#abbbce] group"
             >
               <span class="block group-aria-selected:translate-x-[3px] transition-transform duration-350">
-                {option}
+                {resolved.label}
               </span>
             </ComboboxOption>
-          ))}
+          )}
           class="relative"
         >
           <ComboboxLabel class="font-semibold dark:text-white text-[#333333]">

apps/website/src/routes/docs/headless/(components)/combobox/index.mdx

@@ -65,35 +65,18 @@ import {statusByComponent} from '../../../../../_state/component-statuses';
   ```
 </HeroExample>
 
-<div class="bg-red-200 dark:bg-red-900 p-4 rounded-sm border-l-[3px] dark:border-[#F3F3F3] border-[#333333]">
-  <p class="pb-4">The Combobox component makes use of **portals**. A basic use case for a portal is to prevent overflow issues in your UI. To support portals in Qwik UI, please add the following around your layout.tsx.</p>
-  <CodeExample classes="!mb-0 !p-6 !rounded-md">
-    ```tsx
-    <body>
-      <QwikUIProvider>
-        <slot />
-      </QwikUIProvider>
-    </body>
-    ```
-  </CodeExample>
+Qwik UI's Combobox implementation follows the [WAI-Aria Combobox specifications](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/), along with some additional API's that enhance the flexibility, types, and performance.
 
-  <p class="pt-4">Portals are still currently in **Beta**, as a result, if you'd like to use context within these components, you must pass your context ID using the `contextIds` prop on the `ComboboxPortal` component. If you're not using context, you don't need to do this step.</p>
-    <CodeExample classes="!mb-0 !p-6 !rounded-md">
-    ```tsx
-      <ComboboxPortal contextIds={["my-context-id", "my-context-id-2"]}>
-        <ComboboxListbox>
-          <ComboboxOption>Option</ComboboxOption>
-        </ComboboxListbox>
-      </ComboboxPortal>
-    ```
-  </CodeExample>
-</div>
+<div class="mb-6 flex flex-col gap-2">
+[View Source Code ↗️](https://github.com/qwikifiers/qwik-ui/tree/main/packages/kit-headless/src/components/combobox)
 
-<br/>
+[Report an issue 🚨](https://github.com/qwikifiers/qwik-ui/issues)
 
-> In Beta, we're currently supporting the **Autocomplete** configuration. We aim to support other combobox configurations according to our [roadmap](https://github.com/qwikifiers/qwik-ui/issues/405)
+[Edit This Page 🗒️](<https://github.com/qwikifiers/qwik-ui/edit/main/apps/website/src/routes/docs/headless/(components)/combobox/index.mdx>)
 
-<br/>
+</div>
+
+<br />
 
 ##### ✨ Features
 
@@ -107,18 +90,45 @@ import {statusByComponent} from '../../../../../_state/component-statuses';
 
 <br/>
 
+> In Beta, we're currently supporting the **Autocomplete** configuration. We aim to support other combobox configurations according to our [roadmap](https://github.com/qwikifiers/qwik-ui/issues/405)
 
-Qwik UI's Combobox implementation follows the [WAI-Aria](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) design pattern, along with some additional API's that enhance the flexibility, types, and performance.
-
-<div class="mb-6 flex flex-col gap-2">
-[View Source Code ↗️](https://github.com/qwikifiers/qwik-ui/tree/main/packages/kit-headless/src/components/combobox)
+<br />
 
-[Report an issue 🚨](https://github.com/qwikifiers/qwik-ui/issues)
+<div class="bg-red-200 dark:bg-red-900 p-4 lg:p-6 rounded-xl dark:border-[#F3F3F3] border-[#333333]">
+  <p class="pb-4">The Combobox component makes use of **portals**. A basic use case for a portal is to prevent overflow issues in your UI. To support portals in Qwik UI, please add the following around your layout.tsx.</p>
+  <CodeExample classes="!mb-0 !p-6 !rounded-md">
+    ```tsx
+    import { QwikUIProvider } from '@qwik-ui/headless'; // import Provider component
 
-[Edit This Page 🗒️](<https://github.com/qwikifiers/qwik-ui/edit/main/apps/website/src/routes/docs/headless/(components)/combobox/index.mdx>)
+    // wrap as a direct child to the body tag
+    <body>
+      <QwikUIProvider>
+        <slot />
+      </QwikUIProvider>
+    </body>
+    ```
+  </CodeExample>
 
+  <div class="pt-12 pb-4">
+    #### <ins>**Context Caveats**</ins>
+    <p class="pt-2 pb-4">Portals are still currently in **Beta**, as a result, you may experience an issue using your own context to pass data into the portal children.</p>
+    <p class="pb-4">If you do experience any context related issues, add the following **contextIds** prop to the **ComboboxPortal** component. It takes in an array of string context id's as a prop. We also have a live example below with context.</p>
+    <p class="pb-4">If you are not using context inside the portal children, this will not be an issue.</p>
+
+      <CodeExample classes="!mb-0 !p-6 !rounded-md">
+      ```tsx
+        <ComboboxPortal contextIds={["my-context-id", "my-context-id-2"]}>
+          <ComboboxListbox>
+            <ComboboxOption>Option</ComboboxOption>
+          </ComboboxListbox>
+        </ComboboxPortal> 
+      ```
+    </CodeExample>
+  </div>
 </div>
 
+<br/>
+
 ## Building blocks
 
   <CodeExample>
@@ -128,22 +138,23 @@ Qwik UI's Combobox implementation follows the [WAI-Aria](https://www.w3.org/WAI/
 
     export default component$(() => {
       return (
-        <Combobox>
-          <ComboboxLabel>Label</ComboboxLabel>
+        <Combobox renderOption$={() => (
+            <ComboboxOption>
+              Option
+            </ComboboxOption>
+          )}>
+          <ComboboxLabel>Label Element</ComboboxLabel>
           <ComboboxControl>
             <ComboboxInput />
             <ComboboxTrigger>
-              Button
+              Opens Listbox
             </ComboboxTrigger>
           </ComboboxControl>
           <ComboboxPortal>
-            <ComboboxListbox>
-              <ComboboxOption>Option</ComboboxOption>
-            </ComboboxListbox>
+            <ComboboxListbox />
           </ComboboxPortal>
         </Combobox>
       )
-    })
     ```
 
   </CodeExample>

packages/kit-headless/src/components/combobox/combobox-context.type.ts

@@ -1,10 +1,10 @@
-import { QRL, Signal } from '@builder.io/qwik';
-import { JSX } from '@builder.io/qwik/jsx-runtime';
+import type { Signal } from '@builder.io/qwik';
+import type { ComboboxProps, ResolvedOption } from './combobox';
 
 export interface ComboboxContext<O extends Option = Option> {
   // user's source of truth
-  optionsSig: Signal<{ option: O; key: number }[]>;
-  optionComponent$?: QRL<(option: O, key: number, filteredIndex: number) => JSX.Element>;
+  filteredOptionsSig: Signal<ResolvedOption<O>[]>;
+  renderOption$?: ComboboxProps<O>['renderOption$'];
 
   // element state
   inputValueSig: Signal<string>;