@kushagradhawan/kookie-ui 0.1.65 → 0.1.66

package/src/components/combobox.css

@@ -1,3 +1,4 @@
+/* Combobox styles extend BaseMenu primitives and TextField tokens for search input parity. */
 @import './_internal/base-menu.css';
 @import './text-field.css';
 
@@ -5,6 +6,19 @@
 .rt-ComboboxContent {
   padding: 0 !important;
   max-height: var(--radix-popover-content-available-height);
+  display: flex;
+  flex-direction: column;
+}
+
+.rt-ComboboxCommand {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+}
+
+.rt-ComboboxViewport {
+  padding-top: 0 !important;
 }
 
 .rt-BaseMenuContent:where(.rt-r-size-1) :where(.rt-ComboboxItem) {
@@ -32,21 +46,12 @@
   cursor: var(--cursor-menu-item) !important;
 }
 
-/* Command container uses flex layout with gap */
-.rt-ComboboxCommand {
-  display: flex;
-  flex-direction: column;
-  gap: var(--space-2);
-}
-
 /* Sticky search input with consistent padding */
 .rt-ComboboxSearch {
   position: sticky;
   top: 0;
   z-index: 1;
   padding: var(--base-menu-content-padding);
-  padding-bottom: var(--space-2);
-  border-bottom: 1px solid var(--gray-a3);
   background-color: var(--color-panel);
 }
 
@@ -59,6 +64,11 @@
   width: 100%;
 }
 
+.rt-ScrollAreaRoot:where(.rt-ComboboxScrollArea) {
+  flex: 1;
+  min-height: 0;
+}
+
 /* Map cmdk's selected state to base-menu highlighted state */
 .rt-BaseMenuContent:where(.rt-variant-solid) {
   & :where(.rt-BaseMenuItem.rt-ComboboxItem[data-selected='true']),

package/src/components/combobox.props.tsx

@@ -7,14 +7,22 @@ import type { PropDef } from '../props/prop-def.js';
 
 const sizes = ['1', '2', '3'] as const;
 
+/**
+ * Shared responsive sizing + high contrast support inherited by Combobox.Root.
+ */
 const comboboxRootPropDefs = {
   size: { type: 'enum', className: 'rt-r-size', values: sizes, default: '2', responsive: true },
+  ...highContrastPropDef,
 } satisfies {
   size: PropDef<(typeof sizes)[number]>;
+  highContrast: PropDef<boolean>;
 };
 
 const triggerVariants = ['classic', 'surface', 'soft', 'outline', 'ghost'] as const;
 
+/**
+ * Token-aware props specific to Combobox.Trigger.
+ */
 const comboboxTriggerPropDefs = {
   variant: { type: 'enum', className: 'rt-variant', values: triggerVariants, default: 'surface' },
   panelBackground: {
@@ -23,7 +31,6 @@ const comboboxTriggerPropDefs = {
     values: ['solid', 'translucent'],
   },
   material: { type: 'enum', values: ['solid', 'translucent'] },
-  ...highContrastPropDef,
   error: { type: 'boolean' },
   loading: { type: 'boolean' },
   disabled: { type: 'boolean' },
@@ -36,7 +43,6 @@ const comboboxTriggerPropDefs = {
   variant: PropDef<(typeof triggerVariants)[number]>;
   panelBackground: PropDef<'solid' | 'translucent'>;
   material: PropDef<'solid' | 'translucent'>;
-  highContrast: PropDef<boolean>;
   error: PropDef<boolean>;
   loading: PropDef<boolean>;
   disabled: PropDef<boolean>;
@@ -47,6 +53,9 @@ const comboboxTriggerPropDefs = {
 
 const contentVariants = ['solid', 'soft'] as const;
 
+/**
+ * Styling props for the dropdown surface rendered by Combobox.Content.
+ */
 const comboboxContentPropDefs = {
   size: { type: 'enum', className: 'rt-r-size', values: sizes, default: '2', responsive: true },
   variant: { type: 'enum', className: 'rt-variant', values: contentVariants, default: 'solid' },

package/src/components/combobox.tsx

@@ -1,5 +1,12 @@
 'use client';
 
+/**
+ * Combobox is a compound component built on top of Popover and cmdk's Command list.
+ * It mirrors the Select API while adding search-first behaviors including filtering,
+ * async-friendly state management, and design token support for trigger, content,
+ * and input variants.
+ */
+
 import * as React from 'react';
 import classNames from 'classnames';
 import { useControllableState } from 'radix-ui/internal';
@@ -24,6 +31,9 @@ type TextFieldVariant = (typeof textFieldRootPropDefs.variant.values)[number];
 type ComboboxValue = string | null;
 type CommandFilter = (value: string, search: string, keywords?: string[]) => number;
 
+/**
+ * Additional props supported by Combobox.Root beyond the Radix Popover surface.
+ */
 type ComboboxRootOwnProps = GetPropDefTypes<typeof comboboxRootPropDefs> & {
   value?: ComboboxValue;
   defaultValue?: ComboboxValue;
@@ -42,6 +52,9 @@ type ComboboxRootOwnProps = GetPropDefTypes<typeof comboboxRootPropDefs> & {
   disabled?: boolean;
 };
 
+/**
+ * Internal context shared by all sub-components to avoid prop drilling.
+ */
 interface ComboboxContextValue extends ComboboxRootOwnProps {
   open: boolean;
   setOpen: (open: boolean) => void;
@@ -55,6 +68,10 @@ interface ComboboxContextValue extends ComboboxRootOwnProps {
 }
 
 const ComboboxContext = React.createContext<ComboboxContextValue | null>(null);
+
+/**
+ * Utility hook that ensures consumers are wrapped in Combobox.Root.
+ */
 const useComboboxContext = (caller: string) => {
   const ctx = React.useContext(ComboboxContext);
   if (!ctx) {
@@ -63,7 +80,11 @@ const useComboboxContext = (caller: string) => {
   return ctx;
 };
 
-const ComboboxContentContext = React.createContext<{ variant: 'solid' | 'soft'; size?: string; color?: string; material?: string } | null>(null);
+/**
+ * Context for values that are only available inside Content (e.g., variant, color)
+ * so that Input/Item can style themselves consistently.
+ */
+const ComboboxContentContext = React.createContext<{ variant: 'solid' | 'soft'; size?: string; color?: string; material?: string; highContrast?: boolean } | null>(null);
 const useComboboxContentContext = () => {
   const ctx = React.useContext(ComboboxContentContext);
   return ctx; // Optional - Input might not always be in Content
@@ -71,10 +92,15 @@ const useComboboxContentContext = () => {
 
 type PopoverRootProps = React.ComponentPropsWithoutRef<typeof Popover.Root>;
 interface ComboboxRootProps extends PopoverRootProps, ComboboxRootOwnProps {}
+/**
+ * Root component that wires up Popover behavior, controllable state,
+ * and shared context for trigger/content/input sub-components.
+ */
 const ComboboxRoot: React.FC<ComboboxRootProps> = (props) => {
   const {
     children,
     size = comboboxRootPropDefs.size.default,
+    highContrast = comboboxRootPropDefs.highContrast.default,
     value: valueProp,
     defaultValue = null,
     onValueChange,
@@ -100,7 +126,7 @@ const ComboboxRoot: React.FC<ComboboxRootProps> = (props) => {
   });
 
   const [value, setValue] = useControllableState<ComboboxValue>({
-    prop: valueProp ?? null,
+    prop: valueProp,
     defaultProp: defaultValue,
     onChange: onValueChange,
   });
@@ -130,6 +156,7 @@ const ComboboxRoot: React.FC<ComboboxRootProps> = (props) => {
   const contextValue = React.useMemo<ComboboxContextValue>(
     () => ({
       size,
+      highContrast,
       placeholder,
       searchPlaceholder,
       filter,
@@ -146,7 +173,25 @@ const ComboboxRoot: React.FC<ComboboxRootProps> = (props) => {
       registerItemLabel,
       handleSelect,
     }),
-    [size, placeholder, searchPlaceholder, filter, shouldFilter, loop, disabled, open, setOpen, value, setValue, searchValue, setSearchValue, selectedLabel, registerItemLabel, handleSelect],
+    [
+      size,
+      highContrast,
+      placeholder,
+      searchPlaceholder,
+      filter,
+      shouldFilter,
+      loop,
+      disabled,
+      open,
+      setOpen,
+      value,
+      setValue,
+      searchValue,
+      setSearchValue,
+      selectedLabel,
+      registerItemLabel,
+      handleSelect,
+    ],
   );
 
   return (
@@ -163,15 +208,22 @@ type ComboboxTriggerElement = HTMLButtonElement;
 type ComboboxTriggerOwnProps = GetPropDefTypes<typeof comboboxTriggerPropDefs>;
 type NativeTriggerProps = Omit<React.ComponentPropsWithoutRef<'button'>, 'color'>;
 interface ComboboxTriggerProps extends NativeTriggerProps, MarginProps, ComboboxTriggerOwnProps {}
+/**
+ * Trigger behaves like a styled button that opens the Popover,
+ * syncing size/highContrast from Root while exposing select-like states.
+ */
 const ComboboxTrigger = React.forwardRef<ComboboxTriggerElement, ComboboxTriggerProps>((props, forwardedRef) => {
   const context = useComboboxContext('Combobox.Trigger');
-  const { children, className, placeholder, disabled, readOnly, ...triggerProps } = extractProps(
-    { size: context.size, ...props },
-    { size: comboboxRootPropDefs.size },
+  const { children, className, placeholder, disabled, readOnly, error, loading, color, radius, ...triggerProps } = extractProps(
+    { size: context.size, highContrast: context.highContrast, ...props },
+    { size: comboboxRootPropDefs.size, highContrast: comboboxRootPropDefs.highContrast },
     comboboxTriggerPropDefs,
     marginPropDefs,
   );
 
+  // Extract material and panelBackground separately since they need to be passed as data attributes
+  const { material, panelBackground } = props;
+
   const isDisabled = disabled ?? context.disabled;
   const ariaProps = React.useMemo(
     () => ({
@@ -187,16 +239,35 @@ const ComboboxTrigger = React.forwardRef<ComboboxTriggerElement, ComboboxTrigger
       <span className="rt-SelectTriggerInner">
         <ComboboxValue placeholder={placeholder ?? context.placeholder} />
       </span>
-      <ChevronDownIcon className="rt-SelectIcon" />
+      {loading ? (
+        <div className="rt-SelectIcon rt-SelectLoadingIcon" aria-hidden="true">
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="none">
+            <circle cx="8" cy="8" r="6.5" stroke="currentColor" strokeWidth="1" strokeLinecap="round" strokeDasharray="6 34" strokeDashoffset="0" className="rt-SelectLoadingSpinner" />
+          </svg>
+        </div>
+      ) : (
+        <ChevronDownIcon className="rt-SelectIcon" />
+      )}
     </>
   );
 
+  const { type: buttonType, ...restTriggerProps } = triggerProps;
+  const resolvedButtonType = buttonType ?? 'button';
+
   const triggerChild = (
     <button
+      data-accent-color={color}
+      data-radius={radius}
+      data-panel-background={panelBackground}
+      data-material={material}
+      data-error={error}
+      data-loading={loading}
       data-disabled={isDisabled || undefined}
       data-read-only={readOnly || undefined}
-      {...triggerProps}
+      {...restTriggerProps}
       {...ariaProps}
+      type={resolvedButtonType}
+      disabled={isDisabled}
       ref={forwardedRef}
       className={classNames('rt-reset', 'rt-SelectTrigger', 'rt-ComboboxTrigger', className)}
     >
@@ -212,6 +283,10 @@ type ComboboxValueElement = HTMLSpanElement;
 interface ComboboxValueProps extends React.ComponentPropsWithoutRef<'span'> {
   placeholder?: string;
 }
+/**
+ * Value mirrors Select.Value by showing the selected item's label
+ * or falling back to placeholder text supplied by the consumer or context.
+ */
 const ComboboxValue = React.forwardRef<ComboboxValueElement, ComboboxValueProps>(({ placeholder, children, className, ...valueProps }, forwardedRef) => {
   const context = useComboboxContext('Combobox.Value');
   const displayValue = context.selectedLabel ?? context.value ?? undefined;
@@ -229,6 +304,10 @@ type ComboboxContentOwnProps = GetPropDefTypes<typeof comboboxContentPropDefs> &
   container?: React.ComponentPropsWithoutRef<typeof Popover.Content>['container'];
 };
 interface ComboboxContentProps extends Omit<ComponentPropsWithout<typeof Popover.Content, RemovedProps>, 'size'>, ComboboxContentOwnProps {}
+/**
+ * Content renders the dropdown surface, syncing tokens from the current Theme
+ * and instantiating cmdk's Command list for roving focus + filtering.
+ */
 const ComboboxContent = React.forwardRef<ComboboxContentElement, ComboboxContentProps>((props, forwardedRef) => {
   const context = useComboboxContext('Combobox.Content');
   const themeContext = useThemeContext();
@@ -236,7 +315,7 @@ const ComboboxContent = React.forwardRef<ComboboxContentElement, ComboboxContent
 
   const sizeProp = props.size ?? context.size ?? comboboxContentPropDefs.size.default;
   const variantProp = props.variant ?? comboboxContentPropDefs.variant.default;
-  const highContrastProp = props.highContrast ?? comboboxContentPropDefs.highContrast.default;
+  const highContrastProp = props.highContrast ?? context.highContrast ?? comboboxContentPropDefs.highContrast.default;
 
   const { className, children, color, forceMount, container, ...contentProps } = extractProps(
     { ...props, size: sizeProp, variant: variantProp, highContrast: highContrastProp },
@@ -269,22 +348,18 @@ const ComboboxContent = React.forwardRef<ComboboxContentElement, ComboboxContent
       className={classNames('rt-PopperContent', 'rt-BaseMenuContent', 'rt-ComboboxContent', sanitizedClassName)}
     >
       <Theme asChild>
-        <ScrollArea type="auto">
-          <div className={classNames('rt-BaseMenuViewport', 'rt-ComboboxViewport')}>
-            <ComboboxContentContext.Provider value={{ variant: variantProp, size: String(sizeProp), color: resolvedColor, material: effectiveMaterial }}>
-              <CommandPrimitive
-                loop={context.loop}
-                value={context.searchValue}
-                onValueChange={context.setSearchValue}
-                shouldFilter={context.shouldFilter}
-                filter={context.filter}
-                className="rt-ComboboxCommand"
-              >
-                {children}
-              </CommandPrimitive>
-            </ComboboxContentContext.Provider>
-          </div>
-        </ScrollArea>
+        <ComboboxContentContext.Provider value={{ variant: variantProp, size: String(sizeProp), color: resolvedColor, material: effectiveMaterial, highContrast: highContrastProp }}>
+          <CommandPrimitive
+            loop={context.loop}
+            value={context.searchValue}
+            onValueChange={context.setSearchValue}
+            shouldFilter={context.shouldFilter}
+            filter={context.filter}
+            className="rt-ComboboxCommand"
+          >
+            {children}
+          </CommandPrimitive>
+        </ComboboxContentContext.Provider>
       </Theme>
     </Popover.Content>
   );
@@ -297,6 +372,10 @@ interface ComboboxInputProps extends React.ComponentPropsWithoutRef<typeof Comma
   endAdornment?: React.ReactNode;
   variant?: TextFieldVariant;
 }
+/**
+ * Input composes TextField tokens with cmdk's Command.Input to provide
+ * automatic focus management and optional adornments.
+ */
 const ComboboxInput = React.forwardRef<ComboboxInputElement, ComboboxInputProps>(({ className, startAdornment, endAdornment, placeholder, variant: inputVariant, ...inputProps }, forwardedRef) => {
   const context = useComboboxContext('Combobox.Input');
   const contentContext = useComboboxContentContext();
@@ -307,7 +386,7 @@ const ComboboxInput = React.forwardRef<ComboboxInputElement, ComboboxInputProps>
   // Map combobox variant to textfield variant: solid -> surface, soft -> soft unless overridden
   const textFieldVariant = inputVariant ?? (contentVariant === 'solid' ? 'surface' : 'soft');
 
-  return (
+  const inputField = (
     <div
       className={classNames('rt-TextFieldRoot', 'rt-ComboboxInputRoot', `rt-r-size-${context.size}`, `rt-variant-${textFieldVariant}`)}
       data-accent-color={color}
@@ -323,18 +402,34 @@ const ComboboxInput = React.forwardRef<ComboboxInputElement, ComboboxInputProps>
       ) : null}
     </div>
   );
+
+  if (contentContext) {
+    return <div className="rt-ComboboxSearch">{inputField}</div>;
+  }
+
+  return inputField;
 });
 ComboboxInput.displayName = 'Combobox.Input';
 
 type ComboboxListElement = React.ElementRef<typeof CommandPrimitive.List>;
 interface ComboboxListProps extends React.ComponentPropsWithoutRef<typeof CommandPrimitive.List> {}
+/**
+ * List wraps cmdk's Command.List to inherit base menu styles and provides ScrollArea for the items.
+ */
 const ComboboxList = React.forwardRef<ComboboxListElement, ComboboxListProps>(({ className, ...listProps }, forwardedRef) => (
-  <CommandPrimitive.List {...listProps} ref={forwardedRef} className={classNames('rt-ComboboxList', className)} />
+  <ScrollArea type="auto" className="rt-ComboboxScrollArea" scrollbars="vertical" size="1">
+    <div className={classNames('rt-BaseMenuViewport', 'rt-ComboboxViewport')}>
+      <CommandPrimitive.List {...listProps} ref={forwardedRef} className={classNames('rt-ComboboxList', className)} />
+    </div>
+  </ScrollArea>
 ));
 ComboboxList.displayName = 'Combobox.List';
 
 type ComboboxEmptyElement = React.ElementRef<typeof CommandPrimitive.Empty>;
 interface ComboboxEmptyProps extends React.ComponentPropsWithoutRef<typeof CommandPrimitive.Empty> {}
+/**
+ * Empty renders when no options match the search query.
+ */
 const ComboboxEmpty = React.forwardRef<ComboboxEmptyElement, ComboboxEmptyProps>(({ className, ...emptyProps }, forwardedRef) => (
   <CommandPrimitive.Empty {...emptyProps} ref={forwardedRef} className={classNames('rt-ComboboxEmpty', className)} />
 ));
@@ -342,6 +437,9 @@ ComboboxEmpty.displayName = 'Combobox.Empty';
 
 type ComboboxGroupElement = React.ElementRef<typeof CommandPrimitive.Group>;
 interface ComboboxGroupProps extends React.ComponentPropsWithoutRef<typeof CommandPrimitive.Group> {}
+/**
+ * Group and Label mirror menu semantics for subheadings inside the list.
+ */
 const ComboboxGroup = React.forwardRef<ComboboxGroupElement, ComboboxGroupProps>(({ className, ...groupProps }, forwardedRef) => (
   <CommandPrimitive.Group {...groupProps} ref={forwardedRef} className={classNames('rt-BaseMenuGroup', 'rt-ComboboxGroup', className)} />
 ));
@@ -356,6 +454,9 @@ ComboboxLabel.displayName = 'Combobox.Label';
 
 type ComboboxSeparatorElement = React.ElementRef<typeof CommandPrimitive.Separator>;
 interface ComboboxSeparatorProps extends React.ComponentPropsWithoutRef<typeof CommandPrimitive.Separator> {}
+/**
+ * Separator visually divides logical sections of the option list.
+ */
 const ComboboxSeparator = React.forwardRef<ComboboxSeparatorElement, ComboboxSeparatorProps>(({ className, ...separatorProps }, forwardedRef) => (
   <CommandPrimitive.Separator {...separatorProps} ref={forwardedRef} className={classNames('rt-BaseMenuSeparator', 'rt-ComboboxSeparator', className)} />
 ));
@@ -365,6 +466,10 @@ type ComboboxItemElement = React.ElementRef<typeof CommandPrimitive.Item>;
 interface ComboboxItemProps extends React.ComponentPropsWithoutRef<typeof CommandPrimitive.Item> {
   label?: string;
 }
+/**
+ * Item wires cmdk's selection handling with Kookie UI tokens and
+ * ensures labels are registered for displaying the current value.
+ */
 const ComboboxItem = React.forwardRef<ComboboxItemElement, ComboboxItemProps>(({ className, children, label, value, disabled, onSelect, ...itemProps }, forwardedRef) => {
   const context = useComboboxContext('Combobox.Item');
   const contentContext = useComboboxContentContext();

package/styles.css

@@ -15216,6 +15216,17 @@
 .rt-ComboboxContent{
   padding: 0 !important;
   max-height: var(--radix-popover-content-available-height);
+  display: flex;
+  flex-direction: column;
+}
+.rt-ComboboxCommand{
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+}
+.rt-ComboboxViewport{
+  padding-top: 0 !important;
 }
 .rt-BaseMenuContent:where(.rt-r-size-1) :where(.rt-ComboboxItem){
   --base-menu-item-padding-left: calc(var(--space-5) / 1.2);
@@ -15236,18 +15247,11 @@
   color: inherit !important;
   cursor: var(--cursor-menu-item) !important;
 }
-.rt-ComboboxCommand{
-  display: flex;
-  flex-direction: column;
-  gap: var(--space-2);
-}
 .rt-ComboboxSearch{
   position: sticky;
   top: 0;
   z-index: 1;
   padding: var(--base-menu-content-padding);
-  padding-bottom: var(--space-2);
-  border-bottom: 1px solid var(--gray-a3);
   background-color: var(--color-panel);
 }
 :where([data-panel-background='translucent']) .rt-ComboboxSearch{
@@ -15258,6 +15262,10 @@
 .rt-ComboboxSearch :where(.rt-ComboboxInputRoot){
   width: 100%;
 }
+.rt-ScrollAreaRoot:where(.rt-ComboboxScrollArea){
+  flex: 1;
+  min-height: 0;
+}
 .rt-BaseMenuContent:where(.rt-variant-solid) :where(.rt-BaseMenuItem.rt-ComboboxItem[data-selected='true']),
   .rt-BaseMenuContent:where(.rt-variant-solid) :where(.rt-BaseMenuItem.rt-ComboboxItem[aria-selected='true']){
   background-color: var(--accent-9);