@urbint/cl 1.0.1-2 → 1.0.1-3

package/llms.txt

@@ -766,7 +766,7 @@ interface RenderSelectedValueProps {
 ---
 
 #### DatePicker
-Date and time picker with multiple modes. Supports date only, time only, or date and time selection (side by side).
+Date and time picker with multiple modes. Supports date only, time only, or date and time selection (side by side). Uses a `Modal`-based dropdown on iOS/Android. On web, consider using a native HTML `<input type="date|time|datetime-local">` for better browser integration (see "Cross-Platform Consumption" below).
 
 ```tsx
 import { DatePicker } from '@urbint/cl';
@@ -860,6 +860,286 @@ import { DatePicker } from '@urbint/cl';
 - `time`: Shows hour/minute/AM-PM columns with "Now" and "OK" buttons
 - `datetime`: Shows calendar and time picker side by side with "Now" and "OK" buttons
 
+**Controlled vs Uncontrolled:**
+- **Controlled:** Pass `value` (a `Date`) and `onChange`. The component reflects the `value` you give it.
+- **Uncontrolled:** Omit `value` (or pass `undefined`). Optionally pass `defaultValue` for an initial selection. Internal state manages the selected date.
+- **Important:** Do NOT switch between controlled (`value={someDate}`) and uncontrolled (`value={undefined}`) across re-renders. Pick one pattern. If you need to clear a controlled value, manage a separate `hasValue` flag rather than toggling `value` between a `Date` and `undefined`.
+
+**Cross-Platform Consumption (iOS / Android / Web):**
+
+On **iOS and Android** the DatePicker component works directly and renders a native `Modal` with the calendar/time picker. On **web** the component also works, but you may prefer native HTML inputs for better browser integration. A common pattern is to branch by platform:
+
+```tsx
+import { Platform, View } from 'react-native';
+import { DatePicker, HStack, Box, Pressable } from '@urbint/cl';
+import { X } from 'lucide-react-native';
+
+function DateTimeField({ value, onChange, onClear, label, mode }) {
+  // Web: use native HTML inputs for best browser experience
+  if (Platform.OS === 'web') {
+    const inputType = mode === 'date' ? 'date' 
+      : mode === 'time' ? 'time' 
+      : 'datetime-local';
+
+    return (
+      <Box>
+        <Text variant="caption" weight="semiBold">{label}</Text>
+        <input
+          type={inputType}
+          value={value ?? ''}
+          onChange={(e) => onChange(new Date(e.target.value))}
+          style={{ padding: 12, borderRadius: 4, border: '1px solid #ccc' }}
+        />
+      </Box>
+    );
+  }
+
+  // iOS / Android: use the DatePicker component
+  return (
+    <Box>
+      <HStack alignItems="flex-end" space="sm">
+        <View style={{ flex: 1 }}>
+          <DatePicker
+            label={label}
+            mode={mode}
+            value={value}
+            onChange={onChange}
+          />
+        </View>
+        {value && (
+          <Pressable onPress={onClear} style={{ padding: 12 }}>
+            <X size={18} color="#6B7280" />
+          </Pressable>
+        )}
+      </HStack>
+    </Box>
+  );
+}
+```
+
+**Full Real-World Example (form field with clear button):**
+
+```tsx
+import React, { useState } from 'react';
+import { View } from 'react-native';
+import { DatePicker, HStack, Box, Pressable, Text } from '@urbint/cl';
+import { X } from 'lucide-react-native';
+
+// Helper formatters
+const formatDate = (date: Date) => {
+  const m = String(date.getMonth() + 1).padStart(2, '0');
+  const d = String(date.getDate()).padStart(2, '0');
+  return `${m}/${d}/${date.getFullYear()}`;
+};
+
+const formatTime = (date: Date) => {
+  let h = date.getHours();
+  const min = String(date.getMinutes()).padStart(2, '0');
+  const ampm = h >= 12 ? 'PM' : 'AM';
+  h = h % 12 || 12;
+  return `${String(h).padStart(2, '0')}:${min} ${ampm}`;
+};
+
+const formatDateTime = (date: Date) => `${formatDate(date)} ${formatTime(date)}`;
+
+function MyDateTimeField() {
+  const [selectedDate, setSelectedDate] = useState<Date | undefined>(undefined);
+
+  const handleChange = (date: Date) => {
+    setSelectedDate(date);
+  };
+
+  const handleClear = () => {
+    setSelectedDate(undefined);
+  };
+
+  const formatForPicker = (date: Date, mode: 'date' | 'time' | 'datetime') => {
+    if (mode === 'date') return formatDate(date);
+    if (mode === 'time') return formatTime(date);
+    return formatDateTime(date);
+  };
+
+  return (
+    <Box>
+      <HStack alignItems="flex-end" space="sm">
+        <View style={{ flex: 1 }}>
+          <DatePicker
+            label="Event Date & Time"
+            mode="datetime"
+            value={selectedDate}
+            onChange={handleChange}
+            placeholder="MM/DD/YYYY HH:mm"
+            isRequired
+            formatDate={formatForPicker}
+            showNowButton
+          />
+        </View>
+        {selectedDate && (
+          <Pressable onPress={handleClear} style={{ padding: 12, minHeight: 48, justifyContent: 'center' }}>
+            <X size={18} color="#6B7280" />
+          </Pressable>
+        )}
+      </HStack>
+    </Box>
+  );
+}
+```
+
+**Key Consumption Notes:**
+1. The `value` prop expects a `Date` object or `undefined`. Do not pass strings.
+2. The `onChange` callback receives a `Date` object.
+3. The `formatDate` prop signature is `(date: Date, mode: DatePickerMode) => string` — it controls how the selected value is displayed in the trigger.
+4. For **controlled** usage, always pass `value` as a `Date` or keep it consistently `undefined`; avoid toggling between the two.
+5. Wrap the DatePicker in a `View` with `flex: 1` when placing it inside an `HStack` so it takes available space.
+6. The dropdown uses a `Modal` internally — it renders at the root level, so parent `overflow: 'hidden'` will not clip it.
+
+---
+
+#### Combobox
+Autocomplete input with a dropdown list of suggestions. Supports async loading, custom item rendering, controlled/uncontrolled input, and cross-platform (iOS, Android, Web). Uses a Modal-based dropdown (same pattern as Select) to avoid overflow/zIndex issues.
+
+```tsx
+import { Combobox, ComboboxItem } from '@urbint/cl';
+
+// Basic usage with local filtering
+const [value, setValue] = useState('');
+const [filtered, setFiltered] = useState(items);
+
+const handleInputChange = (text: string) => {
+  setValue(text);
+  setFiltered(
+    items.filter((item) =>
+      item.label.toLowerCase().includes(text.toLowerCase())
+    )
+  );
+};
+
+<Combobox
+  label="Framework"
+  placeholder="Search frameworks..."
+  inputValue={value}
+  onInputChange={handleInputChange}
+  items={filtered}
+  onSelect={(item) => setValue(item.label)}
+/>
+
+// Async loading with search icon
+const [query, setQuery] = useState('');
+const [results, setResults] = useState<ComboboxItem[]>([]);
+const [loading, setLoading] = useState(false);
+
+const handleSearch = (text: string) => {
+  setQuery(text);
+  if (text.length < 2) { setResults([]); return; }
+  setLoading(true);
+  fetchResults(text).then((data) => {
+    setResults(data);
+    setLoading(false);
+  });
+};
+
+<Combobox
+  label="Location"
+  placeholder="Search a city..."
+  inputValue={query}
+  onInputChange={handleSearch}
+  items={results}
+  isLoading={loading}
+  onSelect={(item) => setQuery(item.label)}
+  minChars={2}
+  leftElement={<Icon name="search" />}
+/>
+
+// With error state
+<Combobox
+  label="Location"
+  placeholder="Search..."
+  items={[]}
+  isInvalid
+  errorMessage="Location is required"
+/>
+
+// Disabled
+<Combobox
+  label="Location"
+  placeholder="Search..."
+  items={[]}
+  isDisabled
+/>
+
+// Custom item rendering
+<Combobox
+  items={users}
+  renderItem={({ item, isHighlighted, searchQuery }) => (
+    <HStack space="sm">
+      <Avatar name={item.label} size="xs" />
+      <VStack>
+        <Text weight="semiBold">{item.label}</Text>
+        <Text variant="caption">{item.description}</Text>
+      </VStack>
+    </HStack>
+  )}
+/>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| items | ComboboxItem[] | required | Available items to display in the dropdown |
+| inputValue | string | - | Controlled input value |
+| onInputChange | (text: string) => void | - | Called when input text changes (for search/filtering) |
+| onSelect | (item: ComboboxItem) => void | - | Called when an item is selected |
+| placeholder | string | 'Search...' | Placeholder text |
+| label | string | - | Label text above the input |
+| helperText | string | - | Helper text below the input |
+| errorMessage | string | - | Error message (replaces helperText) |
+| isInvalid | boolean | false | Error state |
+| isDisabled | boolean | false | Disable input |
+| isReadOnly | boolean | false | Read-only input |
+| isRequired | boolean | false | Required field |
+| isLoading | boolean | false | Show loading spinner in dropdown |
+| size | 'sm' \| 'md' \| 'lg' | 'md' | Input size |
+| variant | 'outline' \| 'filled' | 'outline' | Input variant |
+| emptyText | string | 'No results found' | Text shown when no items match |
+| loadingText | string | 'Loading...' | Text shown while loading |
+| leftElement | ReactNode | - | Left element (e.g. search icon) |
+| rightElement | ReactNode | - | Right element (shown left of chevron) |
+| renderItem | (props: RenderComboboxItemProps) => ReactNode | - | Custom render for dropdown items |
+| closeOnSelect | boolean | true | Close dropdown on item select |
+| maxDropdownHeight | number | 260 | Max height of the dropdown list |
+| minChars | number | 0 | Minimum characters before showing dropdown |
+| textInputProps | TextInputProps | - | Additional TextInput props |
+
+**ComboboxItem:**
+```ts
+interface ComboboxItem {
+  value: string;       // Unique identifier
+  label: string;       // Display label
+  description?: string; // Optional secondary text
+  disabled?: boolean;  // Whether item is disabled
+  [key: string]: any;  // Additional custom data
+}
+```
+
+**RenderComboboxItemProps:**
+```ts
+interface RenderComboboxItemProps {
+  item: ComboboxItem;
+  isHighlighted: boolean;
+  isDisabled: boolean;
+  searchQuery: string;
+}
+```
+
+**Controlled vs Uncontrolled:**
+- **Controlled:** Pass `inputValue` and `onInputChange`. You manage the filtering and pass filtered `items`.
+- **Uncontrolled:** Omit `inputValue`. The component manages internal input state. You still need to pass `items` (the component does not filter for you).
+
+**Key Differences from Select:**
+- Combobox has a text input for typing/searching; Select has a trigger button.
+- Combobox is ideal for autocomplete, search-as-you-type, and async data fetching scenarios.
+- Select is better for static, predefined option lists.
+
 ---
 
 #### Slider
@@ -1779,6 +2059,9 @@ import type {
   ModalProps,
   ToastOptions,
   SpacingToken,  // Type for spacing tokens
+  ComboboxProps,
+  ComboboxItem,
+  RenderComboboxItemProps,
 } from '@urbint/cl';
 ```
 
@@ -1888,6 +2171,6 @@ Once configured, ask your AI assistant:
 
 ---
 
-*Last updated: January 2026*
-*Documentation version: 1.1.0*
+*Last updated: February 2026*
+*Documentation version: 1.2.0*
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbint/cl",
-  "version": "1.0.1-2",
+  "version": "1.0.1-3",
   "description": "Enterprise-ready React Native component library built with Unistyles",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/components/Combobox/Combobox.stories.tsx

@@ -0,0 +1,195 @@
+/**
+ * Combobox Stories
+ * Autocomplete input with dropdown suggestions
+ */
+
+import React, { useState, useCallback } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { View, Text } from 'react-native';
+import { Combobox, ComboboxItem } from './Combobox';
+import Svg, { Path } from 'react-native-svg';
+
+const meta: Meta<typeof Combobox> = {
+  title: 'Form/Combobox',
+  component: Combobox,
+  decorators: [
+    (Story) => (
+      <View style={{ padding: 24, maxWidth: 400, minHeight: 400 }}>
+        <Story />
+      </View>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Combobox>;
+
+// Sample data
+const frameworks: ComboboxItem[] = [
+  { value: 'next', label: 'Next.js', description: 'The React framework' },
+  { value: 'svelte', label: 'SvelteKit', description: 'Cybernetically enhanced web apps' },
+  { value: 'nuxt', label: 'Nuxt.js', description: 'The intuitive Vue framework' },
+  { value: 'remix', label: 'Remix', description: 'Full stack web framework' },
+  { value: 'astro', label: 'Astro', description: 'The web framework for content-driven websites' },
+];
+
+const cities: ComboboxItem[] = [
+  { value: 'ny', label: 'New York, NY, United States' },
+  { value: 'sf', label: 'San Francisco, CA, United States' },
+  { value: 'la', label: 'Los Angeles, CA, United States' },
+  { value: 'chicago', label: 'Chicago, IL, United States' },
+  { value: 'seattle', label: 'Seattle, WA, United States' },
+  { value: 'boston', label: 'Boston, MA, United States' },
+  { value: 'miami', label: 'Miami, FL, United States' },
+  { value: 'denver', label: 'Denver, CO, United States' },
+];
+
+// ─── Basic ──────────────────────────────────────────────────────────────────
+
+export const Basic: Story = {
+  render: () => {
+    const [value, setValue] = useState('');
+    const [filtered, setFiltered] = useState(frameworks);
+
+    const handleInputChange = (text: string) => {
+      setValue(text);
+      setFiltered(
+        frameworks.filter((f) =>
+          f.label.toLowerCase().includes(text.toLowerCase())
+        )
+      );
+    };
+
+    return (
+      <Combobox
+        label="Framework"
+        placeholder="Search frameworks..."
+        inputValue={value}
+        onInputChange={handleInputChange}
+        items={filtered}
+        onSelect={(item) => setValue(item.label)}
+      />
+    );
+  },
+};
+
+// ─── With Descriptions ──────────────────────────────────────────────────────
+
+export const WithDescriptions: Story = {
+  render: () => {
+    const [value, setValue] = useState('');
+    const [filtered, setFiltered] = useState(frameworks);
+
+    const handleInputChange = (text: string) => {
+      setValue(text);
+      setFiltered(
+        frameworks.filter((f) =>
+          f.label.toLowerCase().includes(text.toLowerCase())
+        )
+      );
+    };
+
+    return (
+      <Combobox
+        label="Framework"
+        placeholder="Search frameworks..."
+        inputValue={value}
+        onInputChange={handleInputChange}
+        items={filtered}
+        onSelect={(item) => setValue(item.label)}
+        helperText="Choose a framework for your project"
+      />
+    );
+  },
+};
+
+// ─── Async Loading ──────────────────────────────────────────────────────────
+
+export const AsyncLoading: Story = {
+  render: () => {
+    const [value, setValue] = useState('');
+    const [results, setResults] = useState<ComboboxItem[]>([]);
+    const [loading, setLoading] = useState(false);
+
+    const handleInputChange = useCallback((text: string) => {
+      setValue(text);
+      if (text.length < 2) {
+        setResults([]);
+        return;
+      }
+      setLoading(true);
+      // Simulate API call
+      setTimeout(() => {
+        setResults(
+          cities.filter((c) =>
+            c.label.toLowerCase().includes(text.toLowerCase())
+          )
+        );
+        setLoading(false);
+      }, 800);
+    }, []);
+
+    return (
+      <Combobox
+        label="Location"
+        placeholder="Search a city..."
+        inputValue={value}
+        onInputChange={handleInputChange}
+        items={results}
+        isLoading={loading}
+        onSelect={(item) => setValue(item.label)}
+        minChars={2}
+        leftElement={
+          <Svg width={16} height={16} viewBox="0 0 24 24" fill="none">
+            <Path
+              d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
+              stroke="#6B7280"
+              strokeWidth={2}
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </Svg>
+        }
+      />
+    );
+  },
+};
+
+// ─── With Error ─────────────────────────────────────────────────────────────
+
+export const WithError: Story = {
+  render: () => (
+    <Combobox
+      label="Location"
+      placeholder="Search..."
+      items={[]}
+      isInvalid
+      errorMessage="Location is required"
+    />
+  ),
+};
+
+// ─── Disabled ───────────────────────────────────────────────────────────────
+
+export const Disabled: Story = {
+  render: () => (
+    <Combobox
+      label="Location"
+      placeholder="Search..."
+      items={[]}
+      isDisabled
+    />
+  ),
+};
+
+// ─── Sizes ──────────────────────────────────────────────────────────────────
+
+export const Sizes: Story = {
+  render: () => (
+    <View style={{ gap: 16 }}>
+      <Combobox label="Small" placeholder="Search..." items={frameworks} size="sm" />
+      <Combobox label="Medium" placeholder="Search..." items={frameworks} size="md" />
+      <Combobox label="Large" placeholder="Search..." items={frameworks} size="lg" />
+    </View>
+  ),
+};

package/src/components/Combobox/Combobox.tsx

@@ -0,0 +1,675 @@
+/**
+ * Combobox Component
+ * Autocomplete input with a dropdown list of suggestions.
+ * Supports async loading, custom rendering, and cross-platform (iOS, Android, Web).
+ *
+ * Inspired by shadcn/ui Combobox, built with React Native primitives.
+ * Uses Modal-based dropdown (same pattern as Select) to avoid overflow/zIndex issues.
+ */
+
+import React, { forwardRef, useState, useRef, useCallback, useEffect } from 'react';
+import {
+  View,
+  ViewProps,
+  Pressable,
+  Text,
+  ScrollView,
+  TextInput,
+  TextInputProps,
+  StyleSheet,
+  Platform,
+  LayoutRectangle,
+  ActivityIndicator,
+} from 'react-native';
+import Svg, { Path } from 'react-native-svg';
+import { colors, spacing, borderRadius, typography, elevation } from '../../styles/tokens';
+
+// Web portal helper — renders dropdown at document.body to escape all parent overflow/zIndex
+let createPortal: ((children: React.ReactNode, container: Element) => React.ReactPortal) | undefined;
+if (Platform.OS === 'web') {
+  try {
+    createPortal = require('react-dom').createPortal;
+  } catch {}
+}
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ComboboxItem {
+  /** Unique identifier */
+  value: string;
+  /** Display label */
+  label: string;
+  /** Optional secondary text (e.g. subtitle, description) */
+  description?: string;
+  /** Whether the item is disabled */
+  disabled?: boolean;
+  /** Any additional data for custom rendering */
+  [key: string]: any;
+}
+
+export interface RenderComboboxItemProps {
+  item: ComboboxItem;
+  isHighlighted: boolean;
+  isDisabled: boolean;
+  searchQuery: string;
+}
+
+export interface ComboboxProps extends Omit<ViewProps, 'children'> {
+  /** Available items to display in the dropdown */
+  items: ComboboxItem[];
+
+  /** Current input value (controlled) */
+  inputValue?: string;
+
+  /** Called when the input text changes (for async search) */
+  onInputChange?: (text: string) => void;
+
+  /** Called when an item is selected */
+  onSelect?: (item: ComboboxItem) => void;
+
+  /** Placeholder text for the input */
+  placeholder?: string;
+
+  /** Label text above the input */
+  label?: string;
+
+  /** Helper text below the input */
+  helperText?: string;
+
+  /** Error message (replaces helperText) */
+  errorMessage?: string;
+
+  /** Whether the input is invalid */
+  isInvalid?: boolean;
+
+  /** Whether the input is disabled */
+  isDisabled?: boolean;
+
+  /** Whether the input is read-only */
+  isReadOnly?: boolean;
+
+  /** Whether the input is required */
+  isRequired?: boolean;
+
+  /** Show a loading spinner in the dropdown */
+  isLoading?: boolean;
+
+  /** Input size */
+  size?: 'sm' | 'md' | 'lg';
+
+  /** Input variant */
+  variant?: 'outline' | 'filled';
+
+  /** Text shown when no items match */
+  emptyText?: string;
+
+  /** Text shown while loading */
+  loadingText?: string;
+
+  /** Left element (e.g. search icon) */
+  leftElement?: React.ReactNode;
+
+  /** Right element (e.g. clear button) — shown to the left of the chevron */
+  rightElement?: React.ReactNode;
+
+  /** Custom render function for dropdown items */
+  renderItem?: (props: RenderComboboxItemProps) => React.ReactNode;
+
+  /** Whether to close dropdown on select (default: true) */
+  closeOnSelect?: boolean;
+
+  /** Max height of the dropdown list */
+  maxDropdownHeight?: number;
+
+  /** Minimum characters before showing dropdown (default: 0) */
+  minChars?: number;
+
+  /** Additional TextInput props */
+  textInputProps?: Omit<TextInputProps, 'value' | 'onChangeText' | 'placeholder' | 'editable'>;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+export const Combobox = forwardRef<View, ComboboxProps>(
+  (
+    {
+      style,
+      items,
+      inputValue: controlledInputValue,
+      onInputChange,
+      onSelect,
+      placeholder = 'Search...',
+      label,
+      helperText,
+      errorMessage,
+      isInvalid = false,
+      isDisabled = false,
+      isReadOnly = false,
+      isRequired = false,
+      isLoading = false,
+      size = 'md',
+      variant = 'outline',
+      emptyText = 'No results found',
+      loadingText = 'Loading...',
+      leftElement,
+      rightElement,
+      renderItem,
+      closeOnSelect = true,
+      maxDropdownHeight = 260,
+      minChars = 0,
+      textInputProps,
+      ...props
+    },
+    ref
+  ) => {
+    const [isOpen, setIsOpen] = useState(false);
+    const [internalInputValue, setInternalInputValue] = useState('');
+    const [dropdownPosition, setDropdownPosition] = useState<LayoutRectangle | null>(null);
+    const [hoveredItem, setHoveredItem] = useState<string | null>(null);
+    const [isFocused, setIsFocused] = useState(false);
+
+    const inputRef = useRef<TextInput>(null);
+    const wrapperRef = useRef<View>(null);
+
+    const isControlled = controlledInputValue !== undefined;
+    const currentInputValue = isControlled ? controlledInputValue : internalInputValue;
+    const hasError = isInvalid || !!errorMessage;
+
+    // Measure and open the dropdown
+    const measureAndOpen = useCallback(() => {
+      wrapperRef.current?.measureInWindow((x, y, width, height) => {
+        setDropdownPosition({ x, y, width, height });
+        setIsOpen(true);
+      });
+    }, []);
+
+    // Open dropdown when input changes and meets minChars threshold
+    const handleInputChange = useCallback(
+      (text: string) => {
+        if (!isControlled) {
+          setInternalInputValue(text);
+        }
+        onInputChange?.(text);
+
+        if (text.length >= minChars) {
+          measureAndOpen();
+        } else {
+          setIsOpen(false);
+        }
+      },
+      [isControlled, onInputChange, minChars, measureAndOpen]
+    );
+
+    const handleSelect = useCallback(
+      (item: ComboboxItem) => {
+        if (item.disabled) return;
+
+        if (!isControlled) {
+          setInternalInputValue(item.label);
+        }
+        onSelect?.(item);
+
+        if (closeOnSelect) {
+          setIsOpen(false);
+        }
+      },
+      [isControlled, onSelect, closeOnSelect]
+    );
+
+    const handleClose = useCallback(() => {
+      setIsOpen(false);
+      setHoveredItem(null);
+    }, []);
+
+    const handleFocus = useCallback(() => {
+      setIsFocused(true);
+
+      // Show dropdown if we already have items and meet minChars
+      if (currentInputValue.length >= minChars && items.length > 0) {
+        wrapperRef.current?.measureInWindow((x, y, width, height) => {
+          setDropdownPosition({ x, y, width, height });
+          setIsOpen(true);
+        });
+      }
+    }, [currentInputValue, minChars, items.length]);
+
+    const handleBlur = useCallback(() => {
+      setIsFocused(false);
+    }, []);
+
+    const handleClear = useCallback(() => {
+      if (!isControlled) {
+        setInternalInputValue('');
+      }
+      onInputChange?.('');
+      setIsOpen(false);
+      inputRef.current?.focus();
+    }, [isControlled, onInputChange]);
+
+    // Close dropdown when input is below minChars and not loading
+    useEffect(() => {
+      if (isOpen && items.length === 0 && !isLoading && currentInputValue.length < minChars) {
+        setIsOpen(false);
+      }
+    }, [items.length, isLoading, isOpen, currentInputValue, minChars]);
+
+    // Open/re-measure when items arrive or loading starts (for async patterns)
+    useEffect(() => {
+      if ((items.length > 0 || isLoading) && currentInputValue.length >= minChars) {
+        measureAndOpen();
+      }
+    }, [items.length, isLoading, currentInputValue, minChars, measureAndOpen]);
+
+    const showClear = currentInputValue.length > 0 && !isDisabled && !isReadOnly;
+
+    // Calculate dropdown max height
+    const dropdownContentHeight = isLoading
+      ? 56
+      : items.length === 0
+        ? 56
+        : Math.min(items.length * 48 + 16, maxDropdownHeight);
+
+    // Dropdown content — extracted so it can be portalled on web
+    const dropdownOverlay = isOpen ? (
+      <>
+        {/* Backdrop: catches outside taps to close */}
+        <Pressable
+          style={[
+            styles.backdrop,
+            Platform.OS === 'web' && ({ position: 'fixed' } as any),
+          ]}
+          onPress={handleClose}
+        />
+
+        {/* Dropdown */}
+        <View
+          style={[
+            styles.dropdown,
+            Platform.OS === 'web' && ({ position: 'fixed' } as any),
+            dropdownPosition && {
+              top: dropdownPosition.y + dropdownPosition.height + 4,
+              left: dropdownPosition.x,
+              width: dropdownPosition.width,
+              maxHeight: dropdownContentHeight,
+            },
+          ]}
+          onStartShouldSetResponder={() => true}
+        >
+          {/* Loading State */}
+          {isLoading ? (
+            <View style={styles.stateContainer}>
+              <ActivityIndicator size="small" color={colors.brand.blue} />
+              <Text style={styles.stateText}>{loadingText}</Text>
+            </View>
+          ) : items.length === 0 ? (
+            /* Empty State */
+            <View style={styles.stateContainer}>
+              <Text style={styles.stateText}>{emptyText}</Text>
+            </View>
+          ) : (
+            /* Items List */
+            <ScrollView
+              style={styles.itemsList}
+              showsVerticalScrollIndicator
+              nestedScrollEnabled
+              keyboardShouldPersistTaps="handled"
+            >
+              {items.map((item) => {
+                const isItemDisabled = !!item.disabled;
+                const isHovered = hoveredItem === item.value;
+
+                return (
+                  <Pressable
+                    key={item.value}
+                    onPress={() => handleSelect(item)}
+                    onHoverIn={() =>
+                      Platform.OS === 'web' && setHoveredItem(item.value)
+                    }
+                    onHoverOut={() =>
+                      Platform.OS === 'web' && setHoveredItem(null)
+                    }
+                    style={({ pressed }) => [
+                      styles.item,
+                      isItemDisabled && styles.itemDisabled,
+                      pressed && !isItemDisabled && styles.itemPressed,
+                      Platform.OS === 'web' &&
+                        isHovered &&
+                        !isItemDisabled &&
+                        styles.itemHovered,
+                    ]}
+                  >
+                    {renderItem ? (
+                      renderItem({
+                        item,
+                        isHighlighted: isHovered,
+                        isDisabled: isItemDisabled,
+                        searchQuery: currentInputValue,
+                      })
+                    ) : (
+                      <View style={styles.itemContent}>
+                        <Text
+                          style={[
+                            styles.itemText,
+                            isItemDisabled && styles.itemTextDisabled,
+                          ]}
+                          numberOfLines={1}
+                        >
+                          {item.label}
+                        </Text>
+                        {item.description && (
+                          <Text
+                            style={[
+                              styles.itemDescription,
+                              isItemDisabled && styles.itemTextDisabled,
+                            ]}
+                            numberOfLines={1}
+                          >
+                            {item.description}
+                          </Text>
+                        )}
+                      </View>
+                    )}
+                  </Pressable>
+                );
+              })}
+            </ScrollView>
+          )}
+        </View>
+      </>
+    ) : null;
+
+    // On web, portal the dropdown to document.body to escape parent overflow:hidden.
+    // On native, render inline (position: absolute works with RN's layout).
+    const portalledDropdown =
+      dropdownOverlay && Platform.OS === 'web' && createPortal && typeof document !== 'undefined'
+        ? createPortal(dropdownOverlay, document.body)
+        : dropdownOverlay;
+
+    return (
+      <View ref={ref} style={[styles.container, style]} {...props}>
+        {/* Label */}
+        {label && (
+          <Text style={[styles.label, isDisabled && styles.labelDisabled]}>
+            {label}
+            {isRequired && <Text style={styles.required}> *</Text>}
+          </Text>
+        )}
+
+        {/* Input Wrapper */}
+        <View
+          ref={wrapperRef}
+          style={[
+            styles.inputWrapper,
+            styles[variant],
+            styles[size],
+            isFocused && styles.inputFocused,
+            hasError && styles.inputError,
+            isDisabled && styles.inputDisabled,
+          ]}
+        >
+          {/* Left Element */}
+          {leftElement && <View style={styles.leftElement}>{leftElement}</View>}
+
+          {/* Text Input */}
+          <TextInput
+            ref={inputRef}
+            style={[styles.input, styles[`${size}Input` as keyof typeof styles]]}
+            value={currentInputValue}
+            onChangeText={handleInputChange}
+            placeholder={placeholder}
+            placeholderTextColor={colors.text.disabled}
+            editable={!isDisabled && !isReadOnly}
+            onFocus={handleFocus}
+            onBlur={handleBlur}
+            autoCapitalize="none"
+            autoCorrect={false}
+            {...textInputProps}
+          />
+
+          {/* Right Elements: custom + clear + chevron */}
+          <View style={styles.rightContainer}>
+            {rightElement && <View style={styles.rightElement}>{rightElement}</View>}
+
+            {showClear && (
+              <Pressable
+                onPress={handleClear}
+                style={({ hovered }: any) => [
+                  styles.clearButton,
+                  Platform.OS === 'web' && hovered && styles.clearButtonHovered,
+                ]}
+                hitSlop={8}
+              >
+                <Svg width={14} height={14} viewBox="0 0 24 24" fill="none">
+                  <Path
+                    d="M18 6L6 18M6 6l12 12"
+                    stroke={colors.text.secondary}
+                    strokeWidth={2}
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                  />
+                </Svg>
+              </Pressable>
+            )}
+          </View>
+        </View>
+
+        {/* Helper / Error Text */}
+        {(helperText || errorMessage) && (
+          <Text style={[styles.helperText, hasError && styles.errorText]}>
+            {errorMessage || helperText}
+          </Text>
+        )}
+
+        {/* Dropdown — portalled on web to escape parent overflow:hidden */}
+        {portalledDropdown}
+      </View>
+    );
+  }
+);
+
+Combobox.displayName = 'Combobox';
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = StyleSheet.create({
+  container: {
+    width: '100%',
+  },
+
+  // Label
+  label: {
+    fontSize: typography.fontSize.componentLabel,
+    fontWeight: typography.fontWeight.semiBold,
+    color: colors.text.default,
+    marginBottom: spacing.base,
+  },
+  labelDisabled: {
+    color: colors.text.disabled,
+  },
+  required: {
+    color: colors.feedback.error.content,
+  },
+
+  // Input Wrapper
+  inputWrapper: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    borderRadius: borderRadius.md,
+  },
+  outline: {
+    borderWidth: 1,
+    borderColor: colors.border.default,
+    backgroundColor: colors.background.default,
+  },
+  filled: {
+    backgroundColor: colors.background.secondary,
+  },
+  sm: {
+    height: 32,
+    paddingHorizontal: spacing['2x'],
+  },
+  md: {
+    height: 40,
+    paddingHorizontal: spacing['3x'],
+  },
+  lg: {
+    height: 48,
+    paddingHorizontal: spacing['4x'],
+  },
+  inputFocused: {
+    borderColor: colors.border.active,
+  },
+  inputError: {
+    borderColor: colors.border.danger,
+  },
+  inputDisabled: {
+    backgroundColor: colors.background.secondary,
+    borderColor: colors.border.disabled,
+  },
+
+  // Text Input
+  input: {
+    flex: 1,
+    color: colors.text.default,
+    padding: 0,
+    margin: 0,
+    ...Platform.select({
+      web: {
+        outlineStyle: 'none',
+      } as any,
+    }),
+  },
+  smInput: {
+    fontSize: typography.fontSize.small,
+  },
+  mdInput: {
+    fontSize: typography.fontSize.body,
+  },
+  lgInput: {
+    fontSize: typography.fontSize.body,
+  },
+
+  // Elements
+  leftElement: {
+    marginRight: spacing['2x'],
+  },
+  rightContainer: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.base,
+  },
+  rightElement: {
+    marginLeft: spacing.base,
+  },
+  clearButton: {
+    padding: spacing['0.5x'],
+    borderRadius: borderRadius.sm,
+    marginLeft: spacing.base,
+  },
+  clearButtonHovered: {
+    backgroundColor: colors.background.secondary,
+  },
+
+  // Helper / Error
+  helperText: {
+    fontSize: typography.fontSize.caption,
+    color: colors.text.secondary,
+    marginTop: spacing.base,
+  },
+  errorText: {
+    color: colors.feedback.error.content,
+  },
+
+  // Backdrop (replaces Modal overlay — keeps TextInput focusable)
+  backdrop: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    zIndex: 9998,
+    backgroundColor: 'transparent',
+  },
+
+  // Dropdown
+  dropdown: {
+    position: 'absolute',
+    zIndex: 9999,
+    backgroundColor: colors.background.default,
+    borderRadius: borderRadius.md,
+    borderWidth: 1,
+    borderColor: colors.border.default,
+    minWidth: 200,
+    ...Platform.select({
+      ios: {
+        shadowColor: '#000',
+        shadowOffset: { width: 0, height: 4 },
+        shadowOpacity: 0.15,
+        shadowRadius: 12,
+      },
+      android: {
+        elevation: 8,
+      },
+      web: {
+        boxShadow: '0 4px 12px rgba(0,0,0,0.15)',
+      } as any,
+    }),
+  },
+
+  // Items list
+  itemsList: {
+    paddingVertical: spacing.base,
+  },
+
+  // State containers (loading / empty)
+  stateContainer: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingVertical: spacing['4x'],
+    paddingHorizontal: spacing['3x'],
+    gap: spacing['2x'],
+  },
+  stateText: {
+    fontSize: typography.fontSize.body,
+    color: colors.text.secondary,
+  },
+
+  // Individual item
+  item: {
+    paddingVertical: spacing['2x'],
+    paddingHorizontal: spacing['3x'],
+    borderRadius: borderRadius.sm,
+    marginHorizontal: spacing['2x'],
+  },
+  itemHovered: {
+    backgroundColor: colors.background.hover,
+  },
+  itemPressed: {
+    backgroundColor: colors.background.secondary,
+  },
+  itemDisabled: {
+    opacity: 0.5,
+  },
+  itemContent: {
+    flexDirection: 'column',
+    gap: 2,
+  },
+  itemText: {
+    fontSize: typography.fontSize.body,
+    color: colors.text.default,
+  },
+  itemDescription: {
+    fontSize: typography.fontSize.caption,
+    color: colors.text.secondary,
+  },
+  itemTextDisabled: {
+    color: colors.text.disabled,
+  },
+});

package/src/components/Combobox/index.ts

@@ -0,0 +1,6 @@
+export { 
+  Combobox, 
+  type ComboboxProps, 
+  type ComboboxItem, 
+  type RenderComboboxItemProps 
+} from './Combobox';

package/src/components/DatePicker/DatePicker.tsx

@@ -224,6 +224,7 @@ export const DatePicker = forwardRef<View, DatePickerProps>(
     const [dropdownPosition, setDropdownPosition] = useState<LayoutRectangle | null>(null);
     const [viewDate, setViewDate] = useState(controlledValue || defaultValue || new Date());
     const pickerRef = useRef<View>(null);
+    const cachedPositionRef = useRef<LayoutRectangle | null>(null);
 
     const isControlled = controlledValue !== undefined;
     const selectedDate = isControlled ? controlledValue : internalValue;
@@ -302,17 +303,42 @@ export const DatePicker = forwardRef<View, DatePickerProps>(
       return Array.from({ length: 60 }, (_, i) => i);
     }, []);
 
-    const handleOpen = useCallback(() => {
-      if (isDisabled) return;
-
+    // Measure trigger position whenever layout changes so it's ready before user taps
+    const measureTrigger = useCallback(() => {
       pickerRef.current?.measureInWindow((x, y, width, height) => {
-        setDropdownPosition({ x, y, width, height });
-        setIsOpen(true);
-        if (selectedDate) {
-          setViewDate(selectedDate);
+        if (width > 0 && height > 0) {
+          const layout = { x, y, width, height };
+          cachedPositionRef.current = layout;
+          setDropdownPosition(layout);
         }
       });
-    }, [isDisabled, selectedDate]);
+    }, []);
+
+    const handleTriggerLayout = useCallback(() => {
+      // Small delay to ensure native layout is committed
+      requestAnimationFrame(() => {
+        measureTrigger();
+      });
+    }, [measureTrigger]);
+
+    const handleOpen = useCallback(() => {
+      if (isDisabled) return;
+
+      if (selectedDate) {
+        setViewDate(selectedDate);
+      }
+
+      // Use cached position immediately (sync) so dropdown is positioned on first render
+      if (cachedPositionRef.current) {
+        setDropdownPosition(cachedPositionRef.current);
+      }
+
+      // Also re-measure for latest position (async, will update if position changed)
+      measureTrigger();
+
+      // Always open
+      setIsOpen(true);
+    }, [isDisabled, selectedDate, measureTrigger]);
 
     const handleClose = () => {
       setIsOpen(false);
@@ -430,7 +456,9 @@ export const DatePicker = forwardRef<View, DatePickerProps>(
 
         <Pressable
           ref={pickerRef}
+          collapsable={false}
           onPress={handleOpen}
+          onLayout={handleTriggerLayout}
           style={({ hovered }: any) => [
             styles.picker,
             styles[variant],
@@ -466,18 +494,27 @@ export const DatePicker = forwardRef<View, DatePickerProps>(
           animationType="fade"
           onRequestClose={handleClose}
         >
-          <Pressable style={styles.modalOverlay} onPress={handleClose}>
+          <View style={styles.modalContainer}>
+            {/* Backdrop - sibling of dropdown so touches don't propagate */}
+            <Pressable style={StyleSheet.absoluteFillObject} onPress={handleClose} />
+
+            {/* Dropdown */}
             <View
               style={[
                 styles.dropdown,
-                dropdownPosition && {
-                  position: 'absolute',
-                  top: dropdownPosition.y + dropdownPosition.height + 4,
-                  left: dropdownPosition.x,
-                  minWidth: getDropdownMinWidth(),
-                },
+                dropdownPosition
+                  ? {
+                      position: 'absolute',
+                      top: dropdownPosition.y + dropdownPosition.height + 4,
+                      left: dropdownPosition.x,
+                      minWidth: getDropdownMinWidth(),
+                    }
+                  : {
+                      // Centered fallback when position is unknown
+                      alignSelf: 'center',
+                      minWidth: getDropdownMinWidth(),
+                    },
               ]}
-              onStartShouldSetResponder={() => true}
             >
               {/* DateTime Mode - Side by Side Layout */}
               {mode === 'datetime' && (
@@ -898,7 +935,7 @@ export const DatePicker = forwardRef<View, DatePickerProps>(
                 </View>
               )}
             </View>
-          </Pressable>
+          </View>
         </Modal>
       </View>
     );
@@ -986,9 +1023,9 @@ const styles = StyleSheet.create({
   errorText: {
     color: colors.feedback.error.content,
   },
-  modalOverlay: {
+  modalContainer: {
     flex: 1,
-    backgroundColor: 'transparent',
+    justifyContent: 'center',
   },
   dropdown: {
     backgroundColor: colors.background.default,

package/src/components/index.ts

@@ -26,6 +26,7 @@ export * from './Switch';
 export * from './Slider';
 export * from './FormControl';
 export * from './DatePicker';
+export * from './Combobox';
 
 // Feedback Components
 export * from './Alert';