feat(combobox): filter API, major refactor, type changes, docs additions

Author: thejackshelton

apps/website/src/routes/docs/_components/status-banner/status-banner.tsx

@@ -3,7 +3,6 @@ import {
   component$,
   useSignal,
   useStylesScoped$,
-  $,
 } from '@builder.io/qwik';
 import { ComponentStatus } from 'apps/website/src/_state/component-status.type';
 import { getClassByStatus } from '../component-status-badge/component-status-badge';
@@ -86,7 +85,7 @@ export const StatusBanner = component$((props: StatusBannerProps) => {
     animation: fadeOut 0.5s ease forwards;
     margin-top: var(--dynamic-banner-height);
   }
-  
+
   @keyframes fadeOut {
     from {
       opacity: 1;
@@ -103,7 +102,7 @@ export const StatusBanner = component$((props: StatusBannerProps) => {
         ref={ref}
         hidden={isBannerClosedSig.value}
         onAnimationEnd$={() => (isBannerClosedSig.value = true)}
-        class={`${getBackgroundByStatus(props.status)} px-6 py-4 
+        class={`${getBackgroundByStatus(props.status)} px-6 py-4
         rounded-xl md:items-center relative md:flex-row normal-state
         shadow-depth dark:shadow-depth-dark`}
         style={{ marginBottom: `${marginBottom}px` }}

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

@@ -95,10 +95,10 @@ Qwik UI's Accordion implementation follows the [WAI-Aria](https://www.w3.org/WAI
 
 ##### ✨ Features
 
-- Full keyboard navigation.
-- Single or Multi Accordion.
-- Controlled or uncontrolled.
-- Animatable, dynamic, and resumable.
+- Full keyboard navigation
+- Single or Multi Accordion
+- Controlled or uncontrolled
+- Animatable, dynamic, and resumable
 
 <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/accordion)

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

@@ -5,11 +5,12 @@ import {
   ComboboxInput,
   ComboboxLabel,
   ComboboxListbox,
-  ComboboxOption,
   ComboboxPortal,
   ComboboxTrigger,
 } from '@qwik-ui/headless';
 
+import { ComboboxOption } from '../../../../../../../../packages/kit-headless/src/components/combobox';
+
 import { PreviewCodeExample } from '../../../_components/preview-code-example/preview-code-example';
 
 const stringsExample = [
@@ -45,36 +46,20 @@ const objectExample: Array<Trainer> = [
 ];
 
 export const HeroExample = component$(() => {
-  const stringsExampleSig = useSignal(stringsExample);
   const objectExampleSig = useSignal(objectExample);
-  const isComboboxVisibleSig = useSignal(true);
-
-  const onInputChange$ = $((value: string) => {
-    objectExampleSig.value = objectExample.filter((option) => {
-      return option.testLabel.toLowerCase().includes(value.toLowerCase());
-    });
-  });
 
   return (
-    <PreviewCodeExample>
-      <div class="flex flex-col gap-4" q:slot="actualComponent">
-        <button
-          onClick$={() => {
-            isComboboxVisibleSig.value = !isComboboxVisibleSig.value;
-          }}
-        >
-          Toggle Client Side
-        </button>
-        {isComboboxVisibleSig.value && (
+    <>
+      <PreviewCodeExample>
+        <div class="flex flex-col gap-4" q:slot="actualComponent">
           <Combobox
-            options={objectExampleSig}
-            defaultLabel="Randy"
-            onInputChange$={onInputChange$}
+            options={objectExampleSig.value}
             optionValueKey="testValue"
             optionLabelKey="testLabel"
             optionDisabledKey="disabled"
-            optionComponent$={$((option: Trainer, index: number) => (
+            optionComponent$={(option: Trainer, key: number, index: number) => (
               <ComboboxOption
+                key={key}
                 index={index}
                 option={option}
                 style={option.disabled ? { color: 'gray' } : {}}
@@ -84,7 +69,7 @@ export const HeroExample = component$(() => {
                   {option.testLabel}
                 </span>
               </ComboboxOption>
-            ))}
+            )}
             class="relative"
           >
             <ComboboxLabel class=" font-semibold dark:text-white text-[#333333]">
@@ -113,13 +98,13 @@ export const HeroExample = component$(() => {
               <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">
-        <Slot />
-      </div>
-    </PreviewCodeExample>
+        <div q:slot="codeExample">
+          <Slot />
+        </div>
+      </PreviewCodeExample>
+    </>
   );
 });
 
@@ -143,19 +128,17 @@ export const StringCombobox = component$(() => {
 
   const fruitsSig = useSignal(fruits);
 
-  const onInputChange$ = $((value: string) => {
-    fruitsSig.value = fruits.filter((option) => {
-      return option.toLowerCase().includes(value.toLowerCase());
-    });
-  });
-
   return (
     <PreviewCodeExample>
       <div class="flex flex-col gap-4" q:slot="actualComponent">
         <Combobox
-          options={fruitsSig}
+          options={fruitsSig.value}
           defaultLabel="Currant"
-          onInputChange$={onInputChange$}
+          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"
@@ -201,6 +184,71 @@ export const StringCombobox = component$(() => {
   );
 });
 
-export const Example03 = component$(() => {
-  return <PreviewCodeExample></PreviewCodeExample>;
+// Using context example.
+
+import { createContextId, useContextProvider, useContext } from '@builder.io/qwik';
+
+// Create a context ID
+export const AnimalContext = createContextId<string[]>('animal-context');
+
+export const ParentComponent = component$(() => {
+  const animals = ['Armadillo', 'Donkey', 'Baboon', 'Badger', 'Barracuda', 'Bat', 'Bear'];
+  // Provide the animals array to the context under the context ID
+  useContextProvider(AnimalContext, animals);
+
+  return <ContextExample />;
+});
+
+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) => (
+            <ComboboxOption
+              index={index}
+              option={option}
+              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}
+              </span>
+            </ComboboxOption>
+          ))}
+          class="relative"
+        >
+          <ComboboxLabel class="font-semibold dark:text-white text-[#333333]">
+            Animals 🐖
+          </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" />
+            <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"
+                stroke-width="2"
+                class="stroke-white group-aria-expanded:-rotate-180 transition-transform duration-[450ms]"
+                stroke-linecap="round"
+                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 q:slot="codeExample">
+        <Slot />
+      </div>
+    </PreviewCodeExample>
+  );
 });

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

@@ -11,7 +11,7 @@ import {
   ComboboxOption,
 } from '@qwik-ui/headless';
 
-import { HeroExample, StringCombobox, Example03 } from './examples';
+import { HeroExample, ParentComponent, StringCombobox, Example03 } from './examples';
 import { CodeExample } from '../../../_components/code-example/code-example';
 import { KeyboardInteractionTable } from '../../../_components/keyboard-interaction-table/keyboard-interaction-table';
 import { APITable } from '../../../_components/api-table/api-table';
@@ -65,7 +65,7 @@ import {statusByComponent} from '../../../../../_state/component-statuses';
   ```
 </HeroExample>
 
-<div class="bg-[#9A3412] p-4 rounded-sm border-l-[3px] dark:border-[#F3F3F3] border-[#333333]">
+<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
@@ -76,16 +76,37 @@ import {statusByComponent} from '../../../../../_state/component-statuses';
     </body>
     ```
   </CodeExample>
+
+  <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>
 
+<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)
 
+<br/>
+
 ##### ✨ Features
 
-- Full keyboard navigation.
-- Single or Multi Accordion.
-- Controlled or uncontrolled.
-- Animatable, dynamic, and resumable.
+- Full WAI-Aria compliance
+- Full keyboard navigation
+- Autocomplete configuration
+- Can add your own custom filter
+- Controlled or uncontrolled
+- Supports disabled options
+- Animatable, dynamic, and resumable
+
+<br/>
+
 
 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.
 
@@ -127,9 +148,10 @@ Qwik UI's Combobox implementation follows the [WAI-Aria](https://www.w3.org/WAI/
 
   </CodeExample>
 
-## Examples
+## Passing context
+
+<ParentComponent>```tsx ```</ParentComponent>
 
-### EXAMPLE: Frequently Asked Questions
 
 <StringCombobox>```tsx ```</StringCombobox>
 

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

@@ -1,6 +1,7 @@
 import { createContextId } from '@builder.io/qwik';
 import { ComboboxContext } from './combobox-context.type';
 
-const ComboboxContextId = createContextId<ComboboxContext>('combobox');
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const ComboboxContextId = createContextId<ComboboxContext<any>>('combobox');
 
 export default ComboboxContextId;

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

@@ -1,11 +1,13 @@
-import { JSXNode, QRL, Signal } from '@builder.io/qwik';
+import { QRL, Signal } from '@builder.io/qwik';
+import { JSX } from '@builder.io/qwik/jsx-runtime';
 
-export interface ComboboxContext {
+export interface ComboboxContext<O extends Option = Option> {
   // user's source of truth
-  options: Signal<Array<string | Record<string, any>>>;
-  optionComponent$?: QRL<(option: any, index: number) => JSXNode>;
+  optionsSig: Signal<{ option: O; key: number }[]>;
+  optionComponent$?: QRL<(option: O, key: number, filteredIndex: number) => JSX.Element>;
 
   // element state
+  inputValueSig: Signal<string>;
   localId: string;
   labelRef: Signal<HTMLLabelElement | undefined>;
   listboxRef: Signal<HTMLUListElement | undefined>;
@@ -24,11 +26,10 @@ export interface ComboboxContext {
   selectedOptionIndexSig: Signal<number>;
 
   // option settings
-  onInputChange$?: QRL<(value: string) => void>;
-  optionValueKey?: string;
-  optionLabelKey?: string;
-  optionDisabledKey?: string;
+  optionValueKey: string;
+  optionLabelKey: string;
+  optionDisabledKey: string;
 }
 
 // Whether it is a string or an object we want to be able to access the value
-export type Option = ComboboxContext['options']['value'][number];
+export type Option = string | Record<string, unknown>;