docs(select): document props

Author: thejackshelton

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

@@ -262,7 +262,7 @@ Absolutely, documentation is a critical part of the project, and something that
 
 ## Where should I learn the Qwik parts?
 
-If you find yourself stuck on a certain pattern, try taking a look through Qwik UI beta components. For example, the [modal component](https://github.com/qwikifiers/qwik-ui/tree/main/packages/kit-headless/src/components/modal) would be a good one to look through.
+If you find yourself stuck on a certain pattern, try taking a look through Qwik UI beta components. For example, the [select component](https://github.com/qwikifiers/qwik-ui/tree/main/packages/kit-headless/src/components/select) would be a good one to look through.
 
 We're also happy to help! We love experimenting with things and having a blast while doing it.
 

packages/kit-headless/src/components/select/notes.md

@@ -67,10 +67,15 @@ resource: https://joshwayne.com/posts/the-problem-with-dropdowns/
     - [x] Scrollable
     - [x] Aria (controls, roles, etc)
 
+    Nice to haves:
+    - [ ] Example using modular forms with validation
+
 ## Props:
 
     ### State
 
+    #### Root:
+
     name: value
     type: string
     description: uncontrolled select value
@@ -87,17 +92,13 @@ resource: https://joshwayne.com/posts/the-problem-with-dropdowns/
     type: PropFunction
     description: function called when the listbox opens or closes.
 
-    ---
-
-    ### Behavior
-
-    name: placeholder
-    type: string
-    description: sets a placeholder instead of a selected value.
-
     name: disabled
     type: boolean
-    description: When true, the option is disabled.
+    description: disables the select
+
+    name: required
+    type: boolean
+    description: Ensure the user selects an option, as well as custom client and server-side validation.
 
     name: multiple
     type: boolean
@@ -109,6 +110,24 @@ resource: https://joshwayne.com/posts/the-problem-with-dropdowns/
 
     ---
 
+    ### Select Value:
+
+    name: placeholder
+    type: string
+    description: sets a placeholder instead of a selected value.
+
+    ### Select Option:
+
+    name: value
+    type: string
+    description: Give the select a value other than what is displayed in the option.
+
+    name: disabled
+    type: boolean
+    description: When true, the option is disabled.
+
+    ---
+
     ### Forms
 
     name: name

packages/kit-headless/src/components/select/select-inline.tsx

@@ -67,7 +67,7 @@ export const Select: Component<SelectProps> = (props: SelectProps) => {
           );
         }
 
-        child.props.index = currentIndex;
+        child.props._index = currentIndex;
         const isDisabled = child.props.disabled === true;
         const value = (
           child.props.value ? child.props.value : child.props.children

packages/kit-headless/src/components/select/select-option.tsx

@@ -12,32 +12,37 @@ import { isServer, isBrowser } from '@builder.io/qwik/build';
 import SelectContextId from './select-context';
 
 export type SelectOptionProps = PropsOf<'li'> & {
-  index?: number;
+  /** Internal index we get from the inline component. Please see select-inline.tsx */
+  _index?: number;
+
+  /** If true, option is not selectable or focusable. */
   disabled?: boolean;
+
+  /** Selected value associated with the option. */
   value?: string;
 };
 
 export const SelectOption = component$<SelectOptionProps>((props) => {
   /* look at select-inline on how we get the index. */
-  const { index, disabled, ...rest } = props;
+  const { _index, disabled, ...rest } = props;
   const context = useContext(SelectContextId);
   const optionRef = useSignal<HTMLLIElement>();
   const localIndexSig = useSignal<number | null>(null);
-  const optionId = `${context.localId}-${index}`;
+  const optionId = `${context.localId}-${_index}`;
 
   const isSelectedSig = useComputed$(() => {
-    return !disabled && context.selectedIndexSig.value === index;
+    return !disabled && context.selectedIndexSig.value === _index;
   });
 
   const isHighlightedSig = useComputed$(() => {
-    return !disabled && context.highlightedIndexSig.value === index;
+    return !disabled && context.highlightedIndexSig.value === _index;
   });
 
   useTask$(function getIndexTask() {
-    if (index === undefined)
+    if (_index === undefined)
       throw Error('Qwik UI: Select component option cannot find its proper index.');
 
-    localIndexSig.value = index;
+    localIndexSig.value = _index;
   });
 
   useTask$(function scrollableTask({ track, cleanup }) {

packages/kit-headless/src/components/select/select-value.tsx

@@ -3,6 +3,9 @@ import { component$, useContext, type PropsOf, useComputed$ } from '@builder.io/
 import SelectContextId from './select-context';
 
 type SelectValueProps = PropsOf<'span'> & {
+  /**
+   * Optional text displayed when no option is selected.
+   */
   placeholder?: string;
 };
 

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

@@ -17,19 +17,41 @@ import { isBrowser } from '@builder.io/qwik/build';
 import { getActiveDescendant } from './utils';
 
 export type SelectProps = PropsOf<'div'> & {
+  /** The initial selected value (uncontrolled). */
   value?: string;
+
+  /** A signal that contains the current selected value (controlled). */
   'bind:value'?: Signal<string>;
 
-  // our source of truth for the options. We get this at pre-render time in the inline component, that way we do not need textContent, etc.
+  /** Our source of truth for the options. We get this at pre-render time in the inline component, that way we do not need to call native methods such as textContent.
+   **/
   _options?: Opt[];
 
-  // when a value is passed, we check if it's an actual option value, and get its index at pre-render time.
+  /** When a value is passed, we check if it's an actual option value, and get its index at pre-render time.
+   **/
   _valuePropIndex?: number | null;
 
+  /**
+   * QRL handler that runs when a select value changes.
+   * @param value The new value as a string.
+   */
   onChange$?: QRL<(value: string) => void>;
+
+  /**
+   * QRL handler that runs when the listbox opens or closes.
+   * @param open The new state of the listbox.
+   *
+   */
   onOpenChange$?: QRL<(open: boolean) => void>;
 
+  /**
+   *  The native scrollIntoView method is used to scroll the options into view when the user highlights an option. This allows customization of the scroll behavior.
+   */
   scrollOptions?: ScrollIntoViewOptions;
+
+  /**
+   *  Enables looped behavior when the user navigates through the options using the arrow keys.
+   */
   loop?: boolean;
 };