Merge pull request #602 from thejackshelton/improve-combobox

New bind:selectedIndex syntax, bug fixes

Author: thejackshelton

.changeset/honest-timers-dream.md

@@ -0,0 +1,5 @@
+---
+'@qwik-ui/headless': patch
+---
+
+bind syntax Sig suffix removed, new bind:selectedIndex prop, bug fixes

apps/website/src/routes/docs/headless/combobox/examples/hero.tsx

@@ -11,9 +11,11 @@ import {
   ComboboxPopover,
 } from '@qwik-ui/headless';
 
-import { component$ } from '@builder.io/qwik';
+import { component$, useSignal } from '@builder.io/qwik';
 
 export default component$(() => {
+  const selectedOptionIndexSig = useSignal<number>(-1);
+
   const objectExample = [
     { testValue: 'alice', testLabel: 'Alice', disabled: true },
     { testValue: 'joana', testLabel: 'Joana', disabled: true },
@@ -40,32 +42,32 @@ export default component$(() => {
       optionLabelKey="testLabel"
       optionDisabledKey="disabled"
       class="relative"
+      bind:selectedIndex={selectedOptionIndexSig}
     >
       <ComboboxLabel class="font-semibold">Personal Trainers ⚡</ComboboxLabel>
       <ComboboxControl class="relative flex items-center rounded-sm border">
         <ComboboxInput
           placeholder="Jim"
-          class="px-d2 bg-background placeholder:text-muted-foreground w-44 rounded-sm px-2 pr-6"
+          class="px-d2 rounded-sm bg-slate-900 px-2 pr-6 text-white placeholder:text-slate-400"
         />
         <ComboboxTrigger class="group absolute right-0 h-6 w-6">
-          <ComboboxIcon class="stroke-foreground transition-transform duration-[450ms] group-aria-expanded:-rotate-180" />
+          <ComboboxIcon class="stroke-white transition-transform duration-[450ms] group-aria-expanded:-rotate-180" />
         </ComboboxTrigger>
       </ComboboxControl>
-      <ComboboxPopover gutter={8}>
+      <ComboboxPopover class="rounded-sm" gutter={8}>
         <ComboboxListbox
-          class="w-44 rounded-sm border-[1px] border-slate-400 bg-slate-900 px-4 py-2"
+          class="rounded-sm border-[1px] border-slate-400 bg-slate-900 px-4 py-2"
           optionRenderer$={(option: ResolvedOption, index: number) => {
             const myData = option.option as MyData;
             return (
               <ComboboxOption
                 key={option.key}
                 resolved={option}
                 index={index}
-                class="hover:bg-accent aria-disabled:text-muted-foreground aria-disabled:hover:bg-muted aria-selected:border-border aria-selected:bg-accent group flex justify-between rounded-sm border border-transparent px-2 aria-disabled:font-light aria-selected:cursor-pointer"
+                class="aria-disabled:text-muted-foreground data-[highlighted]:border-border group flex justify-between gap-4 rounded-sm border border-transparent px-2 text-white aria-disabled:font-light aria-disabled:hover:border-slate-500 data-[highlighted]:cursor-pointer data-[highlighted]:bg-slate-800"
               >
-                <span class="duration-350 block transition-transform group-aria-selected:translate-x-[3px]">
-                  {myData.testLabel}
-                </span>
+                <span>{myData.testLabel}</span>
+                {selectedOptionIndexSig.value === index && <span>Selected</span>}
               </ComboboxOption>
             );
           }}

apps/website/src/routes/docs/headless/combobox/examples/highlighted-index.tsx

@@ -28,7 +28,7 @@ export default component$(() => {
       <Combobox
         class="w-fit"
         options={highlightedExample}
-        bind:highlightedIndexSig={highlightedIndexSig}
+        bind:highlightedIndex={highlightedIndexSig}
       >
         <ComboboxControl class="relative flex items-center rounded-sm border">
           <ComboboxInput class="px-d2 bg-background placeholder:text-muted-foreground w-fit rounded-sm px-2 pr-6" />

apps/website/src/routes/docs/headless/combobox/examples/placement.tsx

@@ -33,7 +33,7 @@ export default component$(() => {
         class="w-fit"
         options={placementExample}
         optionDisabledKey="myDisabledKey"
-        bind:inputValueSig={inputValueSig}
+        bind:inputValue={inputValueSig}
       >
         <ComboboxLabel>Positions</ComboboxLabel>
         <ComboboxControl class="relative mt-2 flex items-center rounded-sm border">

apps/website/src/routes/docs/headless/combobox/examples/search-bar.tsx

@@ -38,9 +38,9 @@ export default component$(() => {
 
   return (
     <Combobox
-      bind:inputValueSig={inputValueSig}
-      bind:highlightedIndexSig={highlightedIndexSig}
-      bind:isListboxOpenSig={isListboxOpenSig}
+      bind:inputValue={inputValueSig}
+      bind:highlightedIndex={highlightedIndexSig}
+      bind:isListboxOpen={isListboxOpenSig}
       optionValueKey="component"
       class="w-fit"
       options={components}

apps/website/src/routes/docs/headless/combobox/examples/shift.tsx

@@ -26,7 +26,7 @@ export default component$(() => {
         <Combobox
           class="w-fit"
           options={shiftExample}
-          bind:isListboxOpenSig={isListboxOpenSig}
+          bind:isListboxOpen={isListboxOpenSig}
         >
           <ComboboxLabel class=" font-semibold">Fruits 🍓</ComboboxLabel>
           <ComboboxControl class="relative flex items-center rounded-sm border">

apps/website/src/routes/docs/headless/combobox/examples/signal-binds.tsx

@@ -30,8 +30,8 @@ export default component$(() => {
         <Combobox
           class="w-fit"
           options={signalsExample}
-          bind:isListboxOpenSig={isListboxOpenSig}
-          bind:highlightedIndexSig={highlightedIndexSig}
+          bind:isListboxOpen={isListboxOpenSig}
+          bind:highlightedIndex={highlightedIndexSig}
         >
           <ComboboxControl class="relative flex items-center rounded-sm border">
             <ComboboxInput

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

@@ -41,27 +41,6 @@ Qwik UI's Combobox implementation follows the [WAI-Aria Combobox specifications]
 
 <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 />
-
-The Combobox component makes use of [portals](https://qwik.builder.io/docs/cookbook/portal/#portal). 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.
-
-<CodeSnippet name="qwik-ui-provider" />
-
-## **Context Caveats**
-
-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.
-
-If you do experience any context related issues, add the following **contextIds** prop to the **ComboboxPortal** component.
-
-<CodeSnippet name="context-ids" />
-
-It takes in an array of string context id's as a prop. We also have a live example below with context.
-If you are not using context inside the portal children, this will not be an issue.
-
-<br />
-
 ## Building blocks
 
 <CodeSnippet name="building-blocks" />
@@ -91,8 +70,8 @@ If you are not using context inside the portal children, this will not be an iss
       description: `A button that toggles the corresponding listbox when clicked.`,
     },
     {
-      name: 'ComboboxPortal',
-      description: `A portal component that teleports the children outside its parent when the listbox state is open.`,
+      name: 'ComboboxPopover',
+      description: `A Popover component that teleports the children outside its parent when the listbox state is open.`,
     },
     {
       name: 'ComboboxListbox',
@@ -191,29 +170,34 @@ To disable this behavior, set `disableOnBlur={true}` on the Input.
 
 The Combobox component allows you to customize its state signals. This can be useful if you want to control or observe these states externally.
 
-This involves creating a signal and passing it in using the [bind syntax](https://qwik.builder.io/docs/components/rendering/#bind-attribute), such as in the Qwik docs.
+In reality it is a signal prop, we prefer using this syntax, because we believe it is familiar to Qwik developers with the [bind syntax](https://qwik.builder.io/docs/components/rendering/#bind-attribute).
 
 <APITable
   propDescriptors={[
     {
-      name: 'bind:isListboxOpenSig',
+      name: 'bind:inputValue',
       type: 'Signal',
-      description: 'Controls the open state of the listbox.',
+      description: 'Controls the current value of the input.',
     },
     {
-      name: 'bind:isInputFocusedSig',
+      name: 'bind:selectedIndex',
       type: 'Signal',
-      description: 'Controls the focus state of the input.',
+      description: 'Controls the selected option index.',
     },
     {
-      name: 'bind:highlightedIndexSig',
+      name: 'bind:isListboxOpen',
       type: 'Signal',
-      description: 'Controls which option is highlighted.',
+      description: 'Controls the open state of the listbox.',
     },
     {
-      name: 'bind:inputValueSig',
+      name: 'bind:isInputFocused',
       type: 'Signal',
-      description: 'Controls the current value of the input.',
+      description: 'Controls the focus state of the input.',
+    },
+    {
+      name: 'bind:highlightedIndex',
+      type: 'Signal',
+      description: 'Controls which option is highlighted.',
     },
   ]}
 />
@@ -319,22 +303,27 @@ The Combobox component API provides a set of properties that allow you to custom
       description: 'The default label for the combobox.',
     },
     {
-      name: 'bind:isListboxOpenSig',
+      name: 'bind:selectedIndex',
+      type: `Signal<number>`,
+      description: 'A signal for the selected option index.',
+    },
+    {
+      name: 'bind:isListboxOpen',
       type: `Signal<boolean>`,
       description: 'A signal for the open state of the listbox.',
     },
     {
-      name: 'bind:isInputFocusedSig',
+      name: 'bind:isInputFocused',
       type: 'Signal<boolean>',
       description: 'A signal for the focus state of the input.',
     },
     {
-      name: 'bind:inputValueSig',
+      name: 'bind:inputValue',
       type: 'Signal<string>',
       description: 'A signal for the current value of the input.',
     },
     {
-      name: 'bind:highlightedIndexSig',
+      name: 'bind:highlightedIndex',
       type: 'Signal<number>',
       description: 'A signal for the highlighted option index.',
     },

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

@@ -21,7 +21,7 @@ export interface ComboboxContext<O extends Option = Option> {
   isInputFocusedSig: Signal<boolean | undefined>;
   isListboxOpenSig: Signal<boolean | undefined>;
   highlightedIndexSig: Signal<number>;
-  selectedOptionIndexSig: Signal<number>;
+  selectedIndexSig: Signal<number>;
 
   // option settings
   optionValueKey: string;

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

@@ -4,7 +4,6 @@ import {
   useContext,
   useSignal,
   useTask$,
-  type QwikKeyboardEvent,
   type ContextId,
   PropsOf,
 } from '@builder.io/qwik';
@@ -43,7 +42,7 @@ export const ComboboxInput = component$(
       context.inputValueSig.value = inputElement.value;
     });
 
-    const onKeydownBehavior$ = $((e: QwikKeyboardEvent) => {
+    const onKeydownBehavior$ = $((e: KeyboardEvent) => {
       if (e.key === 'ArrowDown') {
         if (context.isListboxOpenSig.value) {
           const nextEnabledOptionIndex = getNextEnabledOptionIndex(
@@ -73,6 +72,7 @@ export const ComboboxInput = component$(
 
       if (e.key === 'Enter') {
         context.isListboxOpenSig.value = false;
+        context.selectedIndexSig.value = context.highlightedIndexSig.value;
 
         // if they somehow manage to highlight a disabled option (bug)
         if (