@noxickon/onyx 4.0.7 → 4.1.0

package/AI-README.md

@@ -2229,6 +2229,125 @@ interface OxCheckboxGroupItemProps extends Omit<
 
 ---
 
+## OxCombobox
+
+Searchable select component with async support.
+
+**Pattern**: Compound Component
+**Sub-components**: `Trigger`, `Content`, `Search`, `Options`, `Option`, `Empty`, `Loading`
+
+### Props
+
+```tsx
+interface OxComboboxProps<T = unknown> {
+  children: ReactNode;
+  className?: string;
+  defaultValue?: T | null; // Uncontrolled default value
+  disabled?: boolean;
+  error?: boolean; // Error state styling
+  onChange?: (value: T | null) => void; // Called when selection changes
+  required?: boolean;
+  value?: T | null; // Controlled value (generic type)
+}
+
+interface OxComboboxTriggerProps extends ComponentPropsWithoutRef<'button'> {
+  placeholder?: string; // Shown when no value selected
+  renderValue?: (value: unknown) => ReactNode; // Custom render for selected value
+}
+
+interface OxComboboxContentProps extends ComponentPropsWithoutRef<'div'> {
+  children: ReactNode; // Search, Options, Empty, Loading components
+}
+
+interface OxComboboxSearchProps extends Omit<ComponentPropsWithoutRef<'input'>, 'onChange'> {
+  debounce?: number; // Debounce delay in ms (default: 300)
+  onChange?: (value: string) => void; // Called with debounced search query
+}
+
+interface OxComboboxOptionsProps extends ComponentPropsWithoutRef<'ul'> {
+  children: ReactNode; // OxCombobox.Option elements
+}
+
+interface OxComboboxOptionProps<T = unknown> extends Omit<ComponentPropsWithoutRef<'li'>, 'value'> {
+  children: ReactNode; // Option content (text, icons, etc.)
+  value: T; // Required - passed to onChange on select
+}
+
+interface OxComboboxEmptyProps extends ComponentPropsWithoutRef<'div'> {
+  children: ReactNode; // Empty state message
+}
+
+interface OxComboboxLoadingProps extends ComponentPropsWithoutRef<'div'> {
+  rows?: number; // Number of skeleton rows (default: 4)
+}
+```
+
+### Example
+
+```tsx
+{
+  /* Basic with local filtering */
+}
+const [selected, setSelected] = useState<Item | null>(null);
+const [query, setQuery] = useState('');
+
+const items = query
+  ? mockItems.filter((item) => item.name.toLowerCase().includes(query.toLowerCase()))
+  : mockItems;
+
+<OxCombobox value={selected} onChange={setSelected}>
+  <OxCombobox.Trigger placeholder="Select item..." renderValue={(v) => (v as Item).name} />
+  <OxCombobox.Content>
+    <OxCombobox.Search placeholder="Search..." onChange={setQuery} />
+    {items.length === 0 ? (
+      <OxCombobox.Empty>No results found</OxCombobox.Empty>
+    ) : (
+      <OxCombobox.Options>
+        {items.map((item) => (
+          <OxCombobox.Option key={item.id} value={item}>
+            {item.name}
+          </OxCombobox.Option>
+        ))}
+      </OxCombobox.Options>
+    )}
+  </OxCombobox.Content>
+</OxCombobox>;
+
+{
+  /* Async with loading state */
+}
+const [loading, setLoading] = useState(false);
+
+const handleSearch = (query: string) => {
+  setLoading(true);
+  fetchItems(query)
+    .then(setItems)
+    .finally(() => setLoading(false));
+};
+
+<OxCombobox value={selected} onChange={setSelected}>
+  <OxCombobox.Trigger placeholder="Search..." renderValue={(v) => (v as Item).name} />
+  <OxCombobox.Content>
+    <OxCombobox.Search debounce={300} onChange={handleSearch} />
+    {loading ? (
+      <OxCombobox.Loading rows={4} />
+    ) : items.length === 0 ? (
+      <OxCombobox.Empty>No results</OxCombobox.Empty>
+    ) : (
+      <OxCombobox.Options>
+        {items.map((item) => (
+          <OxCombobox.Option key={item.id} value={item}>
+            {item.name}
+          </OxCombobox.Option>
+        ))}
+      </OxCombobox.Options>
+    )}
+  </OxCombobox.Content>
+</OxCombobox>;
+```
+
+---
+
 ## OxFileUpload (experimental)
 
 File upload component with drag-and-drop.