@rufous/ui 0.3.19 → 0.3.21

package/dist/main.cjs

@@ -169,13 +169,22 @@ __export(main_exports, {
   WorkItemIcon: () => workItemIcon_default,
   Zoom: () => Zoom,
   getAllCountries: () => getAllCountries2,
+  getCitiesByName: () => getCitiesByName,
   getCitiesOfCountry: () => getCitiesOfCountry,
   getCitiesOfState: () => getCitiesOfState,
+  getCityByName: () => getCityByName,
+  getCountriesByName: () => getCountriesByName,
   getCountryByCode: () => getCountryByCode,
+  getCountryByName: () => getCountryByName,
   getStateByCode: () => getStateByCode,
+  getStateByName: () => getStateByName,
+  getStatesByName: () => getStatesByName,
   getStatesOfCountry: () => getStatesOfCountry,
   transformLegacyTodos: () => transformLegacyTodos,
-  useRufousTheme: () => useRufousTheme
+  useCitiesSearch: () => useCitiesSearch,
+  useCountriesSearch: () => useCountriesSearch,
+  useRufousTheme: () => useRufousTheme,
+  useStatesSearch: () => useStatesSearch
 });
 module.exports = __toCommonJS(main_exports);
 
@@ -4764,6 +4773,7 @@ function DataGrid({
   const menuRef = (0, import_react23.useRef)(null);
   const [showManageColumns, setShowManageColumns] = (0, import_react23.useState)(false);
   const [showAdvancedFilter, setShowAdvancedFilter] = (0, import_react23.useState)(false);
+  const [focusFilterIdx, setFocusFilterIdx] = (0, import_react23.useState)(-1);
   const filterableColumnsProp = initialColumnsProp.filter((c) => c.filterable !== false);
   const initialFilterCol = String(filterableColumnsProp[0]?.field || filterableColumnsProp[0]?.key || "");
   const [advancedFilters, setAdvancedFilters] = (0, import_react23.useState)([
@@ -4812,9 +4822,13 @@ function DataGrid({
       return next;
     });
   }, [initialColumnsProp]);
+  const onFiltersChangeRef = (0, import_react23.useRef)(onFiltersChange);
   (0, import_react23.useEffect)(() => {
-    onFiltersChange?.(advancedFilters);
-  }, [advancedFilters, onFiltersChange]);
+    onFiltersChangeRef.current = onFiltersChange;
+  });
+  (0, import_react23.useEffect)(() => {
+    onFiltersChangeRef.current?.(advancedFilters);
+  }, [advancedFilters]);
   const handleSort = (fieldKey, dir) => {
     if (dir !== void 0) {
       setSortField(fieldKey);
@@ -5083,6 +5097,7 @@ function DataGrid({
       if (!firstCol) return prev;
       return [{ column: String(firstCol.field), operator: getDefaultOperator(firstCol.type), value: "", logic: "AND" }];
     });
+    setFocusFilterIdx(-1);
     setShowAdvancedFilter(false);
   };
   const activeMenuCol = activeMenu ? resolvedColumns.find((c) => String(c.field) === activeMenu) : null;
@@ -5134,7 +5149,18 @@ function DataGrid({
         },
         col.headerName,
         col.sortable !== false && /* @__PURE__ */ import_react23.default.createElement("span", { className: `dg-sort-icon${isSorted ? " dg-sort-icon--active" : ""}` }, isSorted && sortDirection === "asc" && /* @__PURE__ */ import_react23.default.createElement(import_lucide_react2.ChevronUp, { size: 14 }), isSorted && sortDirection === "desc" && /* @__PURE__ */ import_react23.default.createElement(import_lucide_react2.ChevronDown, { size: 14 }), !isSorted && /* @__PURE__ */ import_react23.default.createElement(import_lucide_react2.ChevronsUpDown, { size: 14 }))
-      ), /* @__PURE__ */ import_react23.default.createElement("div", { className: `dg-th-actions${isFiltered ? " dg-th-actions--filtered" : ""}` }, isFiltered && /* @__PURE__ */ import_react23.default.createElement("button", { className: "dg-th-filter-btn", onClick: () => setShowAdvancedFilter(true) }, /* @__PURE__ */ import_react23.default.createElement(import_lucide_react2.Filter, { size: 11 })), !col.disableColumnMenu && /* @__PURE__ */ import_react23.default.createElement(
+      ), /* @__PURE__ */ import_react23.default.createElement("div", { className: `dg-th-actions${isFiltered ? " dg-th-actions--filtered" : ""}` }, isFiltered && /* @__PURE__ */ import_react23.default.createElement(
+        "button",
+        {
+          className: "dg-th-filter-btn",
+          onClick: () => {
+            const idx2 = advancedFilters.findIndex((f) => f.column === colField);
+            setFocusFilterIdx(idx2);
+            setShowAdvancedFilter(true);
+          }
+        },
+        /* @__PURE__ */ import_react23.default.createElement(import_lucide_react2.Filter, { size: 11 })
+      ), !col.disableColumnMenu && /* @__PURE__ */ import_react23.default.createElement(
         "button",
         {
           className: "dg-th-menu-btn",
@@ -5363,7 +5389,7 @@ function DataGrid({
         className: "dg-filter-input",
         placeholder: "Value\u2026",
         value: f.value,
-        autoFocus: idx === advancedFilters.length - 1,
+        autoFocus: focusFilterIdx >= 0 ? idx === focusFilterIdx : idx === advancedFilters.length - 1,
         onChange: (e) => setAdvancedFilters((p) => p.map((fi, i) => i === idx ? { ...fi, value: e.target.value } : fi))
       }
     ));
@@ -9541,7 +9567,9 @@ function SmartSelect({
   value,
   onChange,
   onSearchChange,
+  searchResults = [],
   debounceMs = 300,
+  searchThreshold = 10,
   getOptionLabel,
   getOptionValue,
   getOptionSubLabel,
@@ -9579,14 +9607,20 @@ function SmartSelect({
     return flattenTree(options, getOptionChildren);
   }, [options, getOptionChildren]);
   const flatOptionsList = (0, import_react51.useMemo)(() => flatItems.map((f) => f.option), [flatItems]);
+  const displayOptions = (0, import_react51.useMemo)(() => {
+    if (!searchResults.length) return flatOptionsList;
+    const localKeys = new Set(flatOptionsList.map((o) => getValue(o)));
+    const serverOnly = searchResults.filter((o) => !localKeys.has(getValue(o)));
+    return [...flatOptionsList, ...serverOnly];
+  }, [flatOptionsList, searchResults, getValue]);
   const depthMap = (0, import_react51.useMemo)(() => {
     const map = /* @__PURE__ */ new Map();
     flatItems.forEach(({ option, depth }) => map.set(getValue(option), depth));
     return map;
   }, [flatItems, getValue]);
   const lookup = (0, import_react51.useMemo)(
-    () => buildLookup(options, getOptionChildren, getValue),
-    [options, getOptionChildren, getValue]
+    () => buildLookup(displayOptions, getOptionChildren, getValue),
+    [displayOptions, getOptionChildren, getValue]
   );
   const selectedKeys = (0, import_react51.useMemo)(() => {
     if (multiple) {
@@ -9598,21 +9632,27 @@ function SmartSelect({
     if (!onSearchChange) return;
     if (debounceTimer.current) clearTimeout(debounceTimer.current);
     if (!inputValue) {
-      onSearchChange("");
+      onSearchChange("", 0);
       return;
     }
-    const hasLocalMatch = flatOptionsList.some(
-      (opt) => getOptionLabel(opt).toLowerCase().includes(inputValue.toLowerCase()) || (getOptionSubLabel?.(opt) ?? "").toLowerCase().includes(inputValue.toLowerCase())
-    );
-    if (hasLocalMatch) return;
+    const q = inputValue.toLowerCase();
+    let localCount = 0;
+    for (const opt of flatOptionsList) {
+      if (getOptionLabel(opt).toLowerCase().includes(q) || (getOptionSubLabel?.(opt) ?? "").toLowerCase().includes(q)) {
+        localCount++;
+        if (localCount >= searchThreshold) break;
+      }
+    }
+    if (localCount >= searchThreshold) return;
+    const needed = searchThreshold - localCount;
     if (debounceMs <= 0) {
-      onSearchChange(inputValue);
+      onSearchChange(inputValue, needed);
     } else {
       debounceTimer.current = setTimeout(() => {
-        onSearchChange(inputValue);
+        onSearchChange(inputValue, needed);
       }, debounceMs);
     }
-  }, [onSearchChange, debounceMs, flatOptionsList, getOptionLabel, getOptionSubLabel]);
+  }, [onSearchChange, debounceMs, searchThreshold, flatOptionsList, getOptionLabel, getOptionSubLabel]);
   const handleChange = (0, import_react51.useCallback)((_, newValue) => {
     if (!multiple || !allowChildNodesSelection || !getOptionChildren) {
       onChange?.(newValue);
@@ -9699,10 +9739,12 @@ function SmartSelect({
     if (multiple) {
       const selected = opts.filter((o) => selectedKeys.has(getValue(o)));
       const unselected = opts.filter((o) => !selectedKeys.has(getValue(o)));
-      const filteredRest = inputValue ? unselected.filter(
-        (opt) => getOptionLabel(opt).toLowerCase().includes(inputValue.toLowerCase()) || (getOptionSubLabel?.(opt) ?? "").toLowerCase().includes(inputValue.toLowerCase())
-      ) : unselected;
-      return [...selected, ...filteredRest];
+      if (!inputValue) return [...selected, ...unselected];
+      const q2 = inputValue.toLowerCase();
+      const filteredUnselected = unselected.filter(
+        (opt) => getOptionLabel(opt).toLowerCase().includes(q2) || (getOptionSubLabel?.(opt) ?? "").toLowerCase().includes(q2)
+      ).slice(0, searchThreshold);
+      return [...selected, ...filteredUnselected];
     }
     if (value != null) {
       const selectedLabel = getOptionLabel(value);
@@ -9718,12 +9760,12 @@ function SmartSelect({
     const q = inputValue.toLowerCase();
     return opts.filter(
       (opt) => getOptionLabel(opt).toLowerCase().includes(q) || (getOptionSubLabel?.(opt) ?? "").toLowerCase().includes(q)
-    );
-  }, [filterOptionsProp, multiple, selectedKeys, getValue, getOptionLabel, getOptionSubLabel, value]);
+    ).slice(0, searchThreshold);
+  }, [filterOptionsProp, multiple, selectedKeys, getValue, getOptionLabel, getOptionSubLabel, value, searchThreshold]);
   return /* @__PURE__ */ import_react51.default.createElement(
     Autocomplete,
     {
-      options: flatOptionsList,
+      options: displayOptions,
       value: value ?? (multiple ? [] : null),
       onChange: handleChange,
       onInputChange: handleInputChange,
@@ -13634,12 +13676,54 @@ function getStateNameMap(countryCode) {
   }
   return _stateNameCache.get(countryCode);
 }
+var _allCountriesCache = null;
+function getAllCountriesCached() {
+  if (!_allCountriesCache) _allCountriesCache = import_country_state_city3.Country.getAllCountries();
+  return _allCountriesCache;
+}
+var _allStatesCache = null;
+function getAllStatesCached() {
+  if (!_allStatesCache) {
+    const countryMap = new Map(import_country_state_city3.Country.getAllCountries().map((c) => [c.isoCode, c.name]));
+    _allStatesCache = import_country_state_city3.State.getAllStates().map((s2) => ({
+      ...s2,
+      countryName: countryMap.get(s2.countryCode) ?? ""
+    }));
+  }
+  return _allStatesCache;
+}
+var _allCitiesCache = null;
+function getAllCitiesCached() {
+  if (!_allCitiesCache) {
+    const countryMap = new Map(import_country_state_city3.Country.getAllCountries().map((c) => [c.isoCode, c.name]));
+    const stateMap = new Map(import_country_state_city3.State.getAllStates().map((s2) => [`${s2.countryCode}:${s2.isoCode}`, s2.name]));
+    _allCitiesCache = import_country_state_city3.City.getAllCities().map((city) => ({
+      ...city,
+      cityCode: city.name.slice(0, 3),
+      countryName: countryMap.get(city.countryCode) ?? "",
+      stateName: stateMap.get(`${city.countryCode}:${city.stateCode}`) ?? ""
+    }));
+  }
+  return _allCitiesCache;
+}
 function getAllCountries2() {
-  return import_country_state_city3.Country.getAllCountries();
+  return getAllCountriesCached();
 }
 function getCountryByCode(isoCode) {
   return import_country_state_city3.Country.getCountryByCode(isoCode) ?? void 0;
 }
+function getCountryByName(name, exact = false) {
+  const q = name.toLowerCase();
+  return getAllCountriesCached().find(
+    (c) => exact ? c.name.toLowerCase() === q : c.name.toLowerCase().includes(q)
+  );
+}
+function getCountriesByName(name, exact = false) {
+  const q = name.toLowerCase();
+  return getAllCountriesCached().filter(
+    (c) => exact ? c.name.toLowerCase() === q : c.name.toLowerCase().includes(q)
+  );
+}
 function getStatesOfCountry(countryCode) {
   const countryName = import_country_state_city3.Country.getCountryByCode(countryCode)?.name ?? "";
   return import_country_state_city3.State.getStatesOfCountry(countryCode).map((state) => ({
@@ -13653,6 +13737,18 @@ function getStateByCode(stateCode, countryCode) {
   const countryName = import_country_state_city3.Country.getCountryByCode(countryCode)?.name ?? "";
   return { ...state, countryName };
 }
+function getStateByName(name, exact = false) {
+  const q = name.toLowerCase();
+  return getAllStatesCached().find(
+    (s2) => exact ? s2.name.toLowerCase() === q : s2.name.toLowerCase().includes(q)
+  );
+}
+function getStatesByName(name, exact = false) {
+  const q = name.toLowerCase();
+  return getAllStatesCached().filter(
+    (s2) => exact ? s2.name.toLowerCase() === q : s2.name.toLowerCase().includes(q)
+  );
+}
 function getCitiesOfState(countryCode, stateCode) {
   const countryName = import_country_state_city3.Country.getCountryByCode(countryCode)?.name ?? "";
   const stateName = import_country_state_city3.State.getStateByCodeAndCountry(stateCode, countryCode)?.name ?? "";
@@ -13673,6 +13769,67 @@ function getCitiesOfCountry(countryCode) {
     stateName: stateNameMap.get(city.stateCode) ?? ""
   }));
 }
+function getCityByName(name, exact = false) {
+  const q = name.toLowerCase();
+  return getAllCitiesCached().find(
+    (c) => exact ? c.name.toLowerCase() === q : c.name.toLowerCase().includes(q)
+  );
+}
+function getCitiesByName(name, exact = false) {
+  const q = name.toLowerCase();
+  return getAllCitiesCached().filter(
+    (c) => exact ? c.name.toLowerCase() === q : c.name.toLowerCase().includes(q)
+  );
+}
+
+// lib/utils/useLocationSearch.ts
+var import_react64 = require("react");
+function useDebounced(searcher, debounceMs) {
+  const [query, setQuery] = (0, import_react64.useState)("");
+  const [results, setResults] = (0, import_react64.useState)([]);
+  const timer = (0, import_react64.useRef)(null);
+  (0, import_react64.useEffect)(() => () => {
+    if (timer.current) clearTimeout(timer.current);
+  }, []);
+  const search = (0, import_react64.useCallback)((name) => {
+    setQuery(name);
+    if (timer.current) clearTimeout(timer.current);
+    if (!name.trim()) {
+      setResults([]);
+      return;
+    }
+    timer.current = setTimeout(() => {
+      setResults(searcher(name));
+    }, debounceMs);
+  }, [searcher, debounceMs]);
+  const clear = (0, import_react64.useCallback)(() => {
+    if (timer.current) clearTimeout(timer.current);
+    setQuery("");
+    setResults([]);
+  }, []);
+  return { results, query, search, clear };
+}
+function useCountriesSearch(debounceMs = 300) {
+  const searcher = (0, import_react64.useCallback)(
+    (q) => getCountriesByName(q),
+    []
+  );
+  return useDebounced(searcher, debounceMs);
+}
+function useStatesSearch(debounceMs = 300) {
+  const searcher = (0, import_react64.useCallback)(
+    (q) => getStatesByName(q),
+    []
+  );
+  return useDebounced(searcher, debounceMs);
+}
+function useCitiesSearch(debounceMs = 300) {
+  const searcher = (0, import_react64.useCallback)(
+    (q) => getCitiesByName(q),
+    []
+  );
+  return useDebounced(searcher, debounceMs);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APP_THEMES,
@@ -13815,11 +13972,20 @@ function getCitiesOfCountry(countryCode) {
   WorkItemIcon,
   Zoom,
   getAllCountries,
+  getCitiesByName,
   getCitiesOfCountry,
   getCitiesOfState,
+  getCityByName,
+  getCountriesByName,
   getCountryByCode,
+  getCountryByName,
   getStateByCode,
+  getStateByName,
+  getStatesByName,
   getStatesOfCountry,
   transformLegacyTodos,
-  useRufousTheme
+  useCitiesSearch,
+  useCountriesSearch,
+  useRufousTheme,
+  useStatesSearch
 });

package/dist/main.d.cts

@@ -1909,15 +1909,28 @@ interface SmartSelectProps<T = any> {
     /** Called when selection changes */
     onChange?: (value: T | T[] | null) => void;
     /**
-     * Called when the typed text finds no local match —
-     * use this to trigger an API / server search.
+     * Called when local matches fall below `searchThreshold`.
+     * Receives the current query and how many more records are needed to fill the threshold.
+     * Use this to trigger an API / server search and update `searchResults`.
      */
-    onSearchChange?: (query: string) => void;
+    onSearchChange?: (query: string, needed: number) => void;
+    /**
+     * Results returned by the API for the current query.
+     * Merged with local matches (duplicates excluded) to fill up to `searchThreshold`.
+     * Reset this to [] when the query is cleared.
+     */
+    searchResults?: T[];
     /**
      * Debounce delay in ms before `onSearchChange` fires.
      * Defaults to 300 ms. Pass 0 to disable debouncing.
      */
     debounceMs?: number;
+    /**
+     * Max results to show when a query is active.
+     * If local matches are fewer than this, `onSearchChange` fires with how many more are needed.
+     * Defaults to 10. Pass 0 to always call the API.
+     */
+    searchThreshold?: number;
     /** Primary display label for an option (required) */
     getOptionLabel: (option: T) => string;
     /** Unique key for an option — defaults to the label string */
@@ -1971,7 +1984,7 @@ interface SmartSelectProps<T = any> {
     style?: CSSProperties;
     sx?: SxProp;
 }
-declare function SmartSelect<T = any>({ options, value, onChange, onSearchChange, debounceMs, getOptionLabel, getOptionValue, getOptionSubLabel, getOptionChildren, multiple, allowChildNodesSelection, loading, loadingText, filterOptions: filterOptionsProp, renderOption: renderOptionProp, limitTags, label, placeholder, variant, size, disabled, error, helperText, fullWidth, required, className, style, sx, }: SmartSelectProps<T>): React__default.JSX.Element;
+declare function SmartSelect<T = any>({ options, value, onChange, onSearchChange, searchResults, debounceMs, searchThreshold, getOptionLabel, getOptionValue, getOptionSubLabel, getOptionChildren, multiple, allowChildNodesSelection, loading, loadingText, filterOptions: filterOptionsProp, renderOption: renderOptionProp, limitTags, label, placeholder, variant, size, disabled, error, helperText, fullWidth, required, className, style, sx, }: SmartSelectProps<T>): React__default.JSX.Element;
 
 type ToolbarButton = 'undo' | 'redo' | 'ai' | 'paragraph' | 'fontsize' | 'font' | 'color' | 'bold' | 'italic' | 'strike' | 'link' | 'lineheight' | 'ul' | 'ol' | 'align' | 'indent' | 'outdent' | 'table' | 'image' | 'video' | 'cut' | 'copy' | 'paste' | 'specialchars' | 'code' | 'fullscreen' | 'tts' | 'stt' | 'translate' | 'todo' | '|';
 type EditorVariant = 'default' | 'basic';
@@ -2078,6 +2091,20 @@ interface EnhancedCity extends ICity {
 declare function getAllCountries(): EnhancedCountry[];
 /** Returns a single country by its ISO 2-letter code, or undefined if not found. */
 declare function getCountryByCode(isoCode: string): EnhancedCountry | undefined;
+/**
+ * Returns the first country whose name matches the query (case-insensitive).
+ * Pass `exact: false` (default) to also match partial names.
+ * @param name   Country name or partial name, e.g. "United States" or "united"
+ * @param exact  When true, requires an exact case-insensitive match. Default false.
+ */
+declare function getCountryByName(name: string, exact?: boolean): EnhancedCountry | undefined;
+/**
+ * Returns all countries whose names match the query (case-insensitive, partial by default).
+ * Useful for search-as-you-type flows where you want multiple candidates.
+ * @param name   Search string, e.g. "ind" matches "India", "Indonesia", etc.
+ * @param exact  When true, only exact case-insensitive matches are returned. Default false.
+ */
+declare function getCountriesByName(name: string, exact?: boolean): EnhancedCountry[];
 /**
  * Returns all states for a country, each enriched with `countryName`.
  * @param countryCode  ISO 2-letter country code, e.g. "US"
@@ -2089,6 +2116,18 @@ declare function getStatesOfCountry(countryCode: string): EnhancedState[];
  * @param countryCode  ISO 2-letter country code, e.g. "US"
  */
 declare function getStateByCode(stateCode: string, countryCode: string): EnhancedState | undefined;
+/**
+ * Returns the first state whose name matches the query across **all countries** (case-insensitive).
+ * @param name   State name or partial name, e.g. "Iowa" or "iow"
+ * @param exact  When true, requires an exact case-insensitive match. Default false.
+ */
+declare function getStateByName(name: string, exact?: boolean): EnhancedState | undefined;
+/**
+ * Returns all states whose names match the query across **all countries** (case-insensitive, partial by default).
+ * @param name   Search string, e.g. "new" matches "New York", "New South Wales", etc.
+ * @param exact  When true, only exact case-insensitive matches are returned. Default false.
+ */
+declare function getStatesByName(name: string, exact?: boolean): EnhancedState[];
 /**
  * Returns all cities for a given state, each enriched with `cityCode`, `countryName`,
  * and `stateName`.
@@ -2102,5 +2141,63 @@ declare function getCitiesOfState(countryCode: string, stateCode: string): Enhan
  * @param countryCode  ISO 2-letter country code, e.g. "US"
  */
 declare function getCitiesOfCountry(countryCode: string): EnhancedCity[];
+/**
+ * Returns the first city whose name matches the query across **all countries and states** (case-insensitive).
+ * @param name   City name or partial name, e.g. "Delhi" or "del"
+ * @param exact  When true, requires an exact case-insensitive match. Default false.
+ */
+declare function getCityByName(name: string, exact?: boolean): EnhancedCity | undefined;
+/**
+ * Returns all cities whose names match the query across **all countries and states** (case-insensitive, partial by default).
+ * Searches ~148k cities — prefer the debounced `useCitiesSearch` hook in React components.
+ * @param name   Search string, e.g. "spring" matches "Springfield", "Spring Hill", etc.
+ * @param exact  When true, only exact case-insensitive matches are returned. Default false.
+ */
+declare function getCitiesByName(name: string, exact?: boolean): EnhancedCity[];
+
+interface SearchResult<T> {
+    /** Filtered results. Empty while query is blank. */
+    results: T[];
+    /** Current value of the search input (updated immediately on each keystroke). */
+    query: string;
+    /** Call this on every keystroke — triggers the debounced filter. */
+    search: (name: string) => void;
+    /** Resets query and results immediately. */
+    clear: () => void;
+}
+/**
+ * Debounced country name search across all ~250 countries.
+ *
+ * @param debounceMs  Delay before filtering runs. Defaults to 300 ms.
+ *
+ * @example
+ * const { results, search, clear, query } = useCountriesSearch();
+ * <input onChange={e => search(e.target.value)} value={query} />
+ * {results.map(c => <div key={c.isoCode}>{c.flag} {c.name}</div>)}
+ */
+declare function useCountriesSearch(debounceMs?: number): SearchResult<EnhancedCountry>;
+/**
+ * Debounced state / province name search across **all countries** (~5k states).
+ * No country scoping — results include `countryName` so you can display origin.
+ *
+ * @param debounceMs  Delay before filtering runs. Defaults to 300 ms.
+ *
+ * @example
+ * const { results, search, clear } = useStatesSearch();
+ * // results[0] → { name, isoCode, countryCode, countryName, latitude, longitude }
+ */
+declare function useStatesSearch(debounceMs?: number): SearchResult<EnhancedState>;
+/**
+ * Debounced city name search across **all countries and states** (~148k cities).
+ * No country / state scoping — results include `countryName` and `stateName`.
+ * Debouncing is strongly recommended given the dataset size.
+ *
+ * @param debounceMs  Delay before filtering runs. Defaults to 300 ms.
+ *
+ * @example
+ * const { results, search, clear } = useCitiesSearch(400);
+ * // results[0] → { name, cityCode, stateCode, stateName, countryCode, countryName, … }
+ */
+declare function useCitiesSearch(debounceMs?: number): SearchResult<EnhancedCity>;
 
-export { APP_THEMES, Accordion, AccordionDetails, type AccordionDetailsProps, type AccordionProps, AccordionSummary, type AccordionSummaryProps, type Action, ActivateUserIcon, AddButton, AddressLookup, ArchivedIcon, AssignGroupIcon, Autocomplete, type AutocompleteProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, BaseDialog, Box, type BoxProps, Breadcrumbs, type BreadcrumbsProps, Button, type ButtonProps, CameraIcon, CancelButton, Card, CardActions, type CardActionsProps, CardContent, type CardContentProps, CardHeader, type CardHeaderProps, CardMedia, type CardMediaProps, type CardProps, Checkbox, type CheckboxProps, Chip, type ChipProps, CircularProgress, CircularProgressIcon, type CircularProgressIconProps, CloseIcon, Collapse, type CollapseProps, type Column, CopyIcon, DataGrid, type DataGridProps, DateField, type DateFieldProps, type DateFormatString, DateRangeField, type DateRangeFieldProps, type DateRangeValue, DifficultyAllIcon, DifficultyEasyIcon, DifficultyHardIcon, DifficultyMediumIcon, Divider, type DividerProps, DollarIcon, DownloadIcon, DownloadPdfIcon, Drawer, type DrawerProps, EditChatIcon, EditIcon, EngagementIcon, type EnhancedCity, type EnhancedCountry, type EnhancedState, Fade, type FadeProps, FunctionIcon, Grid, type GridProps, Grow, type GrowProps, HelpOutlinedIcon, HierarchyIcon, IconButton, type IconButtonProps, ImageField, type ImageFieldProps, InactiveGroupIcon, IndustryIcon, InvoiceIcon, Link, type LinkProps, List, ListItem, ListItemButton, type ListItemButtonProps, ListItemIcon, type ListItemIconProps, type ListItemProps, ListItemText, type ListItemTextProps, type ListProps, ListSubheader, type ListSubheaderProps, LocationPinIcon, LogsIcon, Menu, MenuDivider, MenuItem, type MenuItemProps, MenuList, type MenuListProps, type MenuProps, MinExperienceIcon, NineDotMenuIcon, NotificationIcon, type NumberVariant, Paper, type PaperProps, PhoneField, type PhoneFieldProps, Popover, type PopoverProps, Popper, type PopperProps, ProjectIcon, QualificationsIcon, QuestionStatusAllIcon, QuestionStatusPrivateIcon, QuestionStatusPublicIcon, QuestionTypeAllIcon, QuestionTypeCodingIcon, QuestionTypeDescriptiveIcon, QuestionTypeMultipleIcon, QuestionTypeSingleIcon, Radio, RadioGroup, type RadioGroupProps, type RadioProps, Rating, type RatingProps, RefreshIcon, ResendInviteIcon, RolesIcon, RufousAiIcon, RufousBirdIcon, RufousLauncherIcon, RufousLogoLoader, type RufousLogoLoaderProps, RufousTextContent, type RufousTextContentProps, RufousTextEditor, type MentionItemData as RufousTextEditorMentionItem, type RufousTextEditorProps, RufousThemeProvider, Select, type SelectProps, SidebarIcon, Skeleton, type SkeletonProps, Slide, type SlideProps, Slider, type SliderProps, SmartSelect, type SmartSelectProps, Snackbar, type SnackbarProps, SoftSkillsIcon, type SortDirection, Stack, type StackProps, StandardButton, Step, StepButton, type StepButtonProps, StepContent, type StepContentProps, StepLabel, type StepLabelProps, type StepProps, Stepper, type StepperProps, SubmitButton, SubscribeIcon, SuspendUserIcon, Switch, type SwitchProps, type SxProp, Tab, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, TechnicalSkillsIcon, TextField, type TextFieldProps, TickIcon, TimerIcon, ToggleButton, ToggleButtonGroup, type ToggleButtonGroupProps, type ToggleButtonProps, Tooltip, type TooltipProps, TrashIcon, type TreeNode, TreeSelect, type TreeSelectMultiValue, type TreeSelectProps, type TreeSelectValue, Typography, type TypographyProps, UnArchivedIcon, UnsubscribeIcon, UploadIcon, UserAssignIcon, type UserOption, UserSelectionField, type UserSelectionFieldProps, ViewIcon, WorkItemIcon, Zoom, type ZoomProps, getAllCountries, getCitiesOfCountry, getCitiesOfState, getCountryByCode, getStateByCode, getStatesOfCountry, transformLegacyTodos, useRufousTheme };
+export { APP_THEMES, Accordion, AccordionDetails, type AccordionDetailsProps, type AccordionProps, AccordionSummary, type AccordionSummaryProps, type Action, ActivateUserIcon, AddButton, AddressLookup, ArchivedIcon, AssignGroupIcon, Autocomplete, type AutocompleteProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, BaseDialog, Box, type BoxProps, Breadcrumbs, type BreadcrumbsProps, Button, type ButtonProps, CameraIcon, CancelButton, Card, CardActions, type CardActionsProps, CardContent, type CardContentProps, CardHeader, type CardHeaderProps, CardMedia, type CardMediaProps, type CardProps, Checkbox, type CheckboxProps, Chip, type ChipProps, CircularProgress, CircularProgressIcon, type CircularProgressIconProps, CloseIcon, Collapse, type CollapseProps, type Column, CopyIcon, DataGrid, type DataGridProps, DateField, type DateFieldProps, type DateFormatString, DateRangeField, type DateRangeFieldProps, type DateRangeValue, DifficultyAllIcon, DifficultyEasyIcon, DifficultyHardIcon, DifficultyMediumIcon, Divider, type DividerProps, DollarIcon, DownloadIcon, DownloadPdfIcon, Drawer, type DrawerProps, EditChatIcon, EditIcon, EngagementIcon, type EnhancedCity, type EnhancedCountry, type EnhancedState, Fade, type FadeProps, FunctionIcon, Grid, type GridProps, Grow, type GrowProps, HelpOutlinedIcon, HierarchyIcon, IconButton, type IconButtonProps, ImageField, type ImageFieldProps, InactiveGroupIcon, IndustryIcon, InvoiceIcon, Link, type LinkProps, List, ListItem, ListItemButton, type ListItemButtonProps, ListItemIcon, type ListItemIconProps, type ListItemProps, ListItemText, type ListItemTextProps, type ListProps, ListSubheader, type ListSubheaderProps, LocationPinIcon, LogsIcon, Menu, MenuDivider, MenuItem, type MenuItemProps, MenuList, type MenuListProps, type MenuProps, MinExperienceIcon, NineDotMenuIcon, NotificationIcon, type NumberVariant, Paper, type PaperProps, PhoneField, type PhoneFieldProps, Popover, type PopoverProps, Popper, type PopperProps, ProjectIcon, QualificationsIcon, QuestionStatusAllIcon, QuestionStatusPrivateIcon, QuestionStatusPublicIcon, QuestionTypeAllIcon, QuestionTypeCodingIcon, QuestionTypeDescriptiveIcon, QuestionTypeMultipleIcon, QuestionTypeSingleIcon, Radio, RadioGroup, type RadioGroupProps, type RadioProps, Rating, type RatingProps, RefreshIcon, ResendInviteIcon, RolesIcon, RufousAiIcon, RufousBirdIcon, RufousLauncherIcon, RufousLogoLoader, type RufousLogoLoaderProps, RufousTextContent, type RufousTextContentProps, RufousTextEditor, type MentionItemData as RufousTextEditorMentionItem, type RufousTextEditorProps, RufousThemeProvider, Select, type SelectProps, SidebarIcon, Skeleton, type SkeletonProps, Slide, type SlideProps, Slider, type SliderProps, SmartSelect, type SmartSelectProps, Snackbar, type SnackbarProps, SoftSkillsIcon, type SortDirection, Stack, type StackProps, StandardButton, Step, StepButton, type StepButtonProps, StepContent, type StepContentProps, StepLabel, type StepLabelProps, type StepProps, Stepper, type StepperProps, SubmitButton, SubscribeIcon, SuspendUserIcon, Switch, type SwitchProps, type SxProp, Tab, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, TechnicalSkillsIcon, TextField, type TextFieldProps, TickIcon, TimerIcon, ToggleButton, ToggleButtonGroup, type ToggleButtonGroupProps, type ToggleButtonProps, Tooltip, type TooltipProps, TrashIcon, type TreeNode, TreeSelect, type TreeSelectMultiValue, type TreeSelectProps, type TreeSelectValue, Typography, type TypographyProps, UnArchivedIcon, UnsubscribeIcon, UploadIcon, UserAssignIcon, type UserOption, UserSelectionField, type UserSelectionFieldProps, ViewIcon, WorkItemIcon, Zoom, type ZoomProps, getAllCountries, getCitiesByName, getCitiesOfCountry, getCitiesOfState, getCityByName, getCountriesByName, getCountryByCode, getCountryByName, getStateByCode, getStateByName, getStatesByName, getStatesOfCountry, transformLegacyTodos, useCitiesSearch, useCountriesSearch, useRufousTheme, useStatesSearch };

package/dist/main.d.ts

@@ -1909,15 +1909,28 @@ interface SmartSelectProps<T = any> {
     /** Called when selection changes */
     onChange?: (value: T | T[] | null) => void;
     /**
-     * Called when the typed text finds no local match —
-     * use this to trigger an API / server search.
+     * Called when local matches fall below `searchThreshold`.
+     * Receives the current query and how many more records are needed to fill the threshold.
+     * Use this to trigger an API / server search and update `searchResults`.
      */
-    onSearchChange?: (query: string) => void;
+    onSearchChange?: (query: string, needed: number) => void;
+    /**
+     * Results returned by the API for the current query.
+     * Merged with local matches (duplicates excluded) to fill up to `searchThreshold`.
+     * Reset this to [] when the query is cleared.
+     */
+    searchResults?: T[];
     /**
      * Debounce delay in ms before `onSearchChange` fires.
      * Defaults to 300 ms. Pass 0 to disable debouncing.
      */
     debounceMs?: number;
+    /**
+     * Max results to show when a query is active.
+     * If local matches are fewer than this, `onSearchChange` fires with how many more are needed.
+     * Defaults to 10. Pass 0 to always call the API.
+     */
+    searchThreshold?: number;
     /** Primary display label for an option (required) */
     getOptionLabel: (option: T) => string;
     /** Unique key for an option — defaults to the label string */
@@ -1971,7 +1984,7 @@ interface SmartSelectProps<T = any> {
     style?: CSSProperties;
     sx?: SxProp;
 }
-declare function SmartSelect<T = any>({ options, value, onChange, onSearchChange, debounceMs, getOptionLabel, getOptionValue, getOptionSubLabel, getOptionChildren, multiple, allowChildNodesSelection, loading, loadingText, filterOptions: filterOptionsProp, renderOption: renderOptionProp, limitTags, label, placeholder, variant, size, disabled, error, helperText, fullWidth, required, className, style, sx, }: SmartSelectProps<T>): React__default.JSX.Element;
+declare function SmartSelect<T = any>({ options, value, onChange, onSearchChange, searchResults, debounceMs, searchThreshold, getOptionLabel, getOptionValue, getOptionSubLabel, getOptionChildren, multiple, allowChildNodesSelection, loading, loadingText, filterOptions: filterOptionsProp, renderOption: renderOptionProp, limitTags, label, placeholder, variant, size, disabled, error, helperText, fullWidth, required, className, style, sx, }: SmartSelectProps<T>): React__default.JSX.Element;
 
 type ToolbarButton = 'undo' | 'redo' | 'ai' | 'paragraph' | 'fontsize' | 'font' | 'color' | 'bold' | 'italic' | 'strike' | 'link' | 'lineheight' | 'ul' | 'ol' | 'align' | 'indent' | 'outdent' | 'table' | 'image' | 'video' | 'cut' | 'copy' | 'paste' | 'specialchars' | 'code' | 'fullscreen' | 'tts' | 'stt' | 'translate' | 'todo' | '|';
 type EditorVariant = 'default' | 'basic';
@@ -2078,6 +2091,20 @@ interface EnhancedCity extends ICity {
 declare function getAllCountries(): EnhancedCountry[];
 /** Returns a single country by its ISO 2-letter code, or undefined if not found. */
 declare function getCountryByCode(isoCode: string): EnhancedCountry | undefined;
+/**
+ * Returns the first country whose name matches the query (case-insensitive).
+ * Pass `exact: false` (default) to also match partial names.
+ * @param name   Country name or partial name, e.g. "United States" or "united"
+ * @param exact  When true, requires an exact case-insensitive match. Default false.
+ */
+declare function getCountryByName(name: string, exact?: boolean): EnhancedCountry | undefined;
+/**
+ * Returns all countries whose names match the query (case-insensitive, partial by default).
+ * Useful for search-as-you-type flows where you want multiple candidates.
+ * @param name   Search string, e.g. "ind" matches "India", "Indonesia", etc.
+ * @param exact  When true, only exact case-insensitive matches are returned. Default false.
+ */
+declare function getCountriesByName(name: string, exact?: boolean): EnhancedCountry[];
 /**
  * Returns all states for a country, each enriched with `countryName`.
  * @param countryCode  ISO 2-letter country code, e.g. "US"
@@ -2089,6 +2116,18 @@ declare function getStatesOfCountry(countryCode: string): EnhancedState[];
  * @param countryCode  ISO 2-letter country code, e.g. "US"
  */
 declare function getStateByCode(stateCode: string, countryCode: string): EnhancedState | undefined;
+/**
+ * Returns the first state whose name matches the query across **all countries** (case-insensitive).
+ * @param name   State name or partial name, e.g. "Iowa" or "iow"
+ * @param exact  When true, requires an exact case-insensitive match. Default false.
+ */
+declare function getStateByName(name: string, exact?: boolean): EnhancedState | undefined;
+/**
+ * Returns all states whose names match the query across **all countries** (case-insensitive, partial by default).
+ * @param name   Search string, e.g. "new" matches "New York", "New South Wales", etc.
+ * @param exact  When true, only exact case-insensitive matches are returned. Default false.
+ */
+declare function getStatesByName(name: string, exact?: boolean): EnhancedState[];
 /**
  * Returns all cities for a given state, each enriched with `cityCode`, `countryName`,
  * and `stateName`.
@@ -2102,5 +2141,63 @@ declare function getCitiesOfState(countryCode: string, stateCode: string): Enhan
  * @param countryCode  ISO 2-letter country code, e.g. "US"
  */
 declare function getCitiesOfCountry(countryCode: string): EnhancedCity[];
+/**
+ * Returns the first city whose name matches the query across **all countries and states** (case-insensitive).
+ * @param name   City name or partial name, e.g. "Delhi" or "del"
+ * @param exact  When true, requires an exact case-insensitive match. Default false.
+ */
+declare function getCityByName(name: string, exact?: boolean): EnhancedCity | undefined;
+/**
+ * Returns all cities whose names match the query across **all countries and states** (case-insensitive, partial by default).
+ * Searches ~148k cities — prefer the debounced `useCitiesSearch` hook in React components.
+ * @param name   Search string, e.g. "spring" matches "Springfield", "Spring Hill", etc.
+ * @param exact  When true, only exact case-insensitive matches are returned. Default false.
+ */
+declare function getCitiesByName(name: string, exact?: boolean): EnhancedCity[];
+
+interface SearchResult<T> {
+    /** Filtered results. Empty while query is blank. */
+    results: T[];
+    /** Current value of the search input (updated immediately on each keystroke). */
+    query: string;
+    /** Call this on every keystroke — triggers the debounced filter. */
+    search: (name: string) => void;
+    /** Resets query and results immediately. */
+    clear: () => void;
+}
+/**
+ * Debounced country name search across all ~250 countries.
+ *
+ * @param debounceMs  Delay before filtering runs. Defaults to 300 ms.
+ *
+ * @example
+ * const { results, search, clear, query } = useCountriesSearch();
+ * <input onChange={e => search(e.target.value)} value={query} />
+ * {results.map(c => <div key={c.isoCode}>{c.flag} {c.name}</div>)}
+ */
+declare function useCountriesSearch(debounceMs?: number): SearchResult<EnhancedCountry>;
+/**
+ * Debounced state / province name search across **all countries** (~5k states).
+ * No country scoping — results include `countryName` so you can display origin.
+ *
+ * @param debounceMs  Delay before filtering runs. Defaults to 300 ms.
+ *
+ * @example
+ * const { results, search, clear } = useStatesSearch();
+ * // results[0] → { name, isoCode, countryCode, countryName, latitude, longitude }
+ */
+declare function useStatesSearch(debounceMs?: number): SearchResult<EnhancedState>;
+/**
+ * Debounced city name search across **all countries and states** (~148k cities).
+ * No country / state scoping — results include `countryName` and `stateName`.
+ * Debouncing is strongly recommended given the dataset size.
+ *
+ * @param debounceMs  Delay before filtering runs. Defaults to 300 ms.
+ *
+ * @example
+ * const { results, search, clear } = useCitiesSearch(400);
+ * // results[0] → { name, cityCode, stateCode, stateName, countryCode, countryName, … }
+ */
+declare function useCitiesSearch(debounceMs?: number): SearchResult<EnhancedCity>;
 
-export { APP_THEMES, Accordion, AccordionDetails, type AccordionDetailsProps, type AccordionProps, AccordionSummary, type AccordionSummaryProps, type Action, ActivateUserIcon, AddButton, AddressLookup, ArchivedIcon, AssignGroupIcon, Autocomplete, type AutocompleteProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, BaseDialog, Box, type BoxProps, Breadcrumbs, type BreadcrumbsProps, Button, type ButtonProps, CameraIcon, CancelButton, Card, CardActions, type CardActionsProps, CardContent, type CardContentProps, CardHeader, type CardHeaderProps, CardMedia, type CardMediaProps, type CardProps, Checkbox, type CheckboxProps, Chip, type ChipProps, CircularProgress, CircularProgressIcon, type CircularProgressIconProps, CloseIcon, Collapse, type CollapseProps, type Column, CopyIcon, DataGrid, type DataGridProps, DateField, type DateFieldProps, type DateFormatString, DateRangeField, type DateRangeFieldProps, type DateRangeValue, DifficultyAllIcon, DifficultyEasyIcon, DifficultyHardIcon, DifficultyMediumIcon, Divider, type DividerProps, DollarIcon, DownloadIcon, DownloadPdfIcon, Drawer, type DrawerProps, EditChatIcon, EditIcon, EngagementIcon, type EnhancedCity, type EnhancedCountry, type EnhancedState, Fade, type FadeProps, FunctionIcon, Grid, type GridProps, Grow, type GrowProps, HelpOutlinedIcon, HierarchyIcon, IconButton, type IconButtonProps, ImageField, type ImageFieldProps, InactiveGroupIcon, IndustryIcon, InvoiceIcon, Link, type LinkProps, List, ListItem, ListItemButton, type ListItemButtonProps, ListItemIcon, type ListItemIconProps, type ListItemProps, ListItemText, type ListItemTextProps, type ListProps, ListSubheader, type ListSubheaderProps, LocationPinIcon, LogsIcon, Menu, MenuDivider, MenuItem, type MenuItemProps, MenuList, type MenuListProps, type MenuProps, MinExperienceIcon, NineDotMenuIcon, NotificationIcon, type NumberVariant, Paper, type PaperProps, PhoneField, type PhoneFieldProps, Popover, type PopoverProps, Popper, type PopperProps, ProjectIcon, QualificationsIcon, QuestionStatusAllIcon, QuestionStatusPrivateIcon, QuestionStatusPublicIcon, QuestionTypeAllIcon, QuestionTypeCodingIcon, QuestionTypeDescriptiveIcon, QuestionTypeMultipleIcon, QuestionTypeSingleIcon, Radio, RadioGroup, type RadioGroupProps, type RadioProps, Rating, type RatingProps, RefreshIcon, ResendInviteIcon, RolesIcon, RufousAiIcon, RufousBirdIcon, RufousLauncherIcon, RufousLogoLoader, type RufousLogoLoaderProps, RufousTextContent, type RufousTextContentProps, RufousTextEditor, type MentionItemData as RufousTextEditorMentionItem, type RufousTextEditorProps, RufousThemeProvider, Select, type SelectProps, SidebarIcon, Skeleton, type SkeletonProps, Slide, type SlideProps, Slider, type SliderProps, SmartSelect, type SmartSelectProps, Snackbar, type SnackbarProps, SoftSkillsIcon, type SortDirection, Stack, type StackProps, StandardButton, Step, StepButton, type StepButtonProps, StepContent, type StepContentProps, StepLabel, type StepLabelProps, type StepProps, Stepper, type StepperProps, SubmitButton, SubscribeIcon, SuspendUserIcon, Switch, type SwitchProps, type SxProp, Tab, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, TechnicalSkillsIcon, TextField, type TextFieldProps, TickIcon, TimerIcon, ToggleButton, ToggleButtonGroup, type ToggleButtonGroupProps, type ToggleButtonProps, Tooltip, type TooltipProps, TrashIcon, type TreeNode, TreeSelect, type TreeSelectMultiValue, type TreeSelectProps, type TreeSelectValue, Typography, type TypographyProps, UnArchivedIcon, UnsubscribeIcon, UploadIcon, UserAssignIcon, type UserOption, UserSelectionField, type UserSelectionFieldProps, ViewIcon, WorkItemIcon, Zoom, type ZoomProps, getAllCountries, getCitiesOfCountry, getCitiesOfState, getCountryByCode, getStateByCode, getStatesOfCountry, transformLegacyTodos, useRufousTheme };
+export { APP_THEMES, Accordion, AccordionDetails, type AccordionDetailsProps, type AccordionProps, AccordionSummary, type AccordionSummaryProps, type Action, ActivateUserIcon, AddButton, AddressLookup, ArchivedIcon, AssignGroupIcon, Autocomplete, type AutocompleteProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, BaseDialog, Box, type BoxProps, Breadcrumbs, type BreadcrumbsProps, Button, type ButtonProps, CameraIcon, CancelButton, Card, CardActions, type CardActionsProps, CardContent, type CardContentProps, CardHeader, type CardHeaderProps, CardMedia, type CardMediaProps, type CardProps, Checkbox, type CheckboxProps, Chip, type ChipProps, CircularProgress, CircularProgressIcon, type CircularProgressIconProps, CloseIcon, Collapse, type CollapseProps, type Column, CopyIcon, DataGrid, type DataGridProps, DateField, type DateFieldProps, type DateFormatString, DateRangeField, type DateRangeFieldProps, type DateRangeValue, DifficultyAllIcon, DifficultyEasyIcon, DifficultyHardIcon, DifficultyMediumIcon, Divider, type DividerProps, DollarIcon, DownloadIcon, DownloadPdfIcon, Drawer, type DrawerProps, EditChatIcon, EditIcon, EngagementIcon, type EnhancedCity, type EnhancedCountry, type EnhancedState, Fade, type FadeProps, FunctionIcon, Grid, type GridProps, Grow, type GrowProps, HelpOutlinedIcon, HierarchyIcon, IconButton, type IconButtonProps, ImageField, type ImageFieldProps, InactiveGroupIcon, IndustryIcon, InvoiceIcon, Link, type LinkProps, List, ListItem, ListItemButton, type ListItemButtonProps, ListItemIcon, type ListItemIconProps, type ListItemProps, ListItemText, type ListItemTextProps, type ListProps, ListSubheader, type ListSubheaderProps, LocationPinIcon, LogsIcon, Menu, MenuDivider, MenuItem, type MenuItemProps, MenuList, type MenuListProps, type MenuProps, MinExperienceIcon, NineDotMenuIcon, NotificationIcon, type NumberVariant, Paper, type PaperProps, PhoneField, type PhoneFieldProps, Popover, type PopoverProps, Popper, type PopperProps, ProjectIcon, QualificationsIcon, QuestionStatusAllIcon, QuestionStatusPrivateIcon, QuestionStatusPublicIcon, QuestionTypeAllIcon, QuestionTypeCodingIcon, QuestionTypeDescriptiveIcon, QuestionTypeMultipleIcon, QuestionTypeSingleIcon, Radio, RadioGroup, type RadioGroupProps, type RadioProps, Rating, type RatingProps, RefreshIcon, ResendInviteIcon, RolesIcon, RufousAiIcon, RufousBirdIcon, RufousLauncherIcon, RufousLogoLoader, type RufousLogoLoaderProps, RufousTextContent, type RufousTextContentProps, RufousTextEditor, type MentionItemData as RufousTextEditorMentionItem, type RufousTextEditorProps, RufousThemeProvider, Select, type SelectProps, SidebarIcon, Skeleton, type SkeletonProps, Slide, type SlideProps, Slider, type SliderProps, SmartSelect, type SmartSelectProps, Snackbar, type SnackbarProps, SoftSkillsIcon, type SortDirection, Stack, type StackProps, StandardButton, Step, StepButton, type StepButtonProps, StepContent, type StepContentProps, StepLabel, type StepLabelProps, type StepProps, Stepper, type StepperProps, SubmitButton, SubscribeIcon, SuspendUserIcon, Switch, type SwitchProps, type SxProp, Tab, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, TechnicalSkillsIcon, TextField, type TextFieldProps, TickIcon, TimerIcon, ToggleButton, ToggleButtonGroup, type ToggleButtonGroupProps, type ToggleButtonProps, Tooltip, type TooltipProps, TrashIcon, type TreeNode, TreeSelect, type TreeSelectMultiValue, type TreeSelectProps, type TreeSelectValue, Typography, type TypographyProps, UnArchivedIcon, UnsubscribeIcon, UploadIcon, UserAssignIcon, type UserOption, UserSelectionField, type UserSelectionFieldProps, ViewIcon, WorkItemIcon, Zoom, type ZoomProps, getAllCountries, getCitiesByName, getCitiesOfCountry, getCitiesOfState, getCityByName, getCountriesByName, getCountryByCode, getCountryByName, getStateByCode, getStateByName, getStatesByName, getStatesOfCountry, transformLegacyTodos, useCitiesSearch, useCountriesSearch, useRufousTheme, useStatesSearch };

package/dist/main.js

@@ -4628,6 +4628,7 @@ function DataGrid({
   const menuRef = useRef10(null);
   const [showManageColumns, setShowManageColumns] = useState9(false);
   const [showAdvancedFilter, setShowAdvancedFilter] = useState9(false);
+  const [focusFilterIdx, setFocusFilterIdx] = useState9(-1);
   const filterableColumnsProp = initialColumnsProp.filter((c) => c.filterable !== false);
   const initialFilterCol = String(filterableColumnsProp[0]?.field || filterableColumnsProp[0]?.key || "");
   const [advancedFilters, setAdvancedFilters] = useState9([
@@ -4676,9 +4677,13 @@ function DataGrid({
       return next;
     });
   }, [initialColumnsProp]);
+  const onFiltersChangeRef = useRef10(onFiltersChange);
   useEffect9(() => {
-    onFiltersChange?.(advancedFilters);
-  }, [advancedFilters, onFiltersChange]);
+    onFiltersChangeRef.current = onFiltersChange;
+  });
+  useEffect9(() => {
+    onFiltersChangeRef.current?.(advancedFilters);
+  }, [advancedFilters]);
   const handleSort = (fieldKey, dir) => {
     if (dir !== void 0) {
       setSortField(fieldKey);
@@ -4947,6 +4952,7 @@ function DataGrid({
       if (!firstCol) return prev;
       return [{ column: String(firstCol.field), operator: getDefaultOperator(firstCol.type), value: "", logic: "AND" }];
     });
+    setFocusFilterIdx(-1);
     setShowAdvancedFilter(false);
   };
   const activeMenuCol = activeMenu ? resolvedColumns.find((c) => String(c.field) === activeMenu) : null;
@@ -4998,7 +5004,18 @@ function DataGrid({
         },
         col.headerName,
         col.sortable !== false && /* @__PURE__ */ React75.createElement("span", { className: `dg-sort-icon${isSorted ? " dg-sort-icon--active" : ""}` }, isSorted && sortDirection === "asc" && /* @__PURE__ */ React75.createElement(ChevronUp, { size: 14 }), isSorted && sortDirection === "desc" && /* @__PURE__ */ React75.createElement(ChevronDown, { size: 14 }), !isSorted && /* @__PURE__ */ React75.createElement(ChevronsUpDown, { size: 14 }))
-      ), /* @__PURE__ */ React75.createElement("div", { className: `dg-th-actions${isFiltered ? " dg-th-actions--filtered" : ""}` }, isFiltered && /* @__PURE__ */ React75.createElement("button", { className: "dg-th-filter-btn", onClick: () => setShowAdvancedFilter(true) }, /* @__PURE__ */ React75.createElement(Filter, { size: 11 })), !col.disableColumnMenu && /* @__PURE__ */ React75.createElement(
+      ), /* @__PURE__ */ React75.createElement("div", { className: `dg-th-actions${isFiltered ? " dg-th-actions--filtered" : ""}` }, isFiltered && /* @__PURE__ */ React75.createElement(
+        "button",
+        {
+          className: "dg-th-filter-btn",
+          onClick: () => {
+            const idx2 = advancedFilters.findIndex((f) => f.column === colField);
+            setFocusFilterIdx(idx2);
+            setShowAdvancedFilter(true);
+          }
+        },
+        /* @__PURE__ */ React75.createElement(Filter, { size: 11 })
+      ), !col.disableColumnMenu && /* @__PURE__ */ React75.createElement(
         "button",
         {
           className: "dg-th-menu-btn",
@@ -5227,7 +5244,7 @@ function DataGrid({
         className: "dg-filter-input",
         placeholder: "Value\u2026",
         value: f.value,
-        autoFocus: idx === advancedFilters.length - 1,
+        autoFocus: focusFilterIdx >= 0 ? idx === focusFilterIdx : idx === advancedFilters.length - 1,
         onChange: (e) => setAdvancedFilters((p) => p.map((fi, i) => i === idx ? { ...fi, value: e.target.value } : fi))
       }
     ));
@@ -9474,7 +9491,9 @@ function SmartSelect({
   value,
   onChange,
   onSearchChange,
+  searchResults = [],
   debounceMs = 300,
+  searchThreshold = 10,
   getOptionLabel,
   getOptionValue,
   getOptionSubLabel,
@@ -9512,14 +9531,20 @@ function SmartSelect({
     return flattenTree(options, getOptionChildren);
   }, [options, getOptionChildren]);
   const flatOptionsList = useMemo3(() => flatItems.map((f) => f.option), [flatItems]);
+  const displayOptions = useMemo3(() => {
+    if (!searchResults.length) return flatOptionsList;
+    const localKeys = new Set(flatOptionsList.map((o) => getValue(o)));
+    const serverOnly = searchResults.filter((o) => !localKeys.has(getValue(o)));
+    return [...flatOptionsList, ...serverOnly];
+  }, [flatOptionsList, searchResults, getValue]);
   const depthMap = useMemo3(() => {
     const map = /* @__PURE__ */ new Map();
     flatItems.forEach(({ option, depth }) => map.set(getValue(option), depth));
     return map;
   }, [flatItems, getValue]);
   const lookup = useMemo3(
-    () => buildLookup(options, getOptionChildren, getValue),
-    [options, getOptionChildren, getValue]
+    () => buildLookup(displayOptions, getOptionChildren, getValue),
+    [displayOptions, getOptionChildren, getValue]
   );
   const selectedKeys = useMemo3(() => {
     if (multiple) {
@@ -9531,21 +9556,27 @@ function SmartSelect({
     if (!onSearchChange) return;
     if (debounceTimer.current) clearTimeout(debounceTimer.current);
     if (!inputValue) {
-      onSearchChange("");
+      onSearchChange("", 0);
       return;
     }
-    const hasLocalMatch = flatOptionsList.some(
-      (opt) => getOptionLabel(opt).toLowerCase().includes(inputValue.toLowerCase()) || (getOptionSubLabel?.(opt) ?? "").toLowerCase().includes(inputValue.toLowerCase())
-    );
-    if (hasLocalMatch) return;
+    const q = inputValue.toLowerCase();
+    let localCount = 0;
+    for (const opt of flatOptionsList) {
+      if (getOptionLabel(opt).toLowerCase().includes(q) || (getOptionSubLabel?.(opt) ?? "").toLowerCase().includes(q)) {
+        localCount++;
+        if (localCount >= searchThreshold) break;
+      }
+    }
+    if (localCount >= searchThreshold) return;
+    const needed = searchThreshold - localCount;
     if (debounceMs <= 0) {
-      onSearchChange(inputValue);
+      onSearchChange(inputValue, needed);
     } else {
       debounceTimer.current = setTimeout(() => {
-        onSearchChange(inputValue);
+        onSearchChange(inputValue, needed);
       }, debounceMs);
     }
-  }, [onSearchChange, debounceMs, flatOptionsList, getOptionLabel, getOptionSubLabel]);
+  }, [onSearchChange, debounceMs, searchThreshold, flatOptionsList, getOptionLabel, getOptionSubLabel]);
   const handleChange = useCallback11((_, newValue) => {
     if (!multiple || !allowChildNodesSelection || !getOptionChildren) {
       onChange?.(newValue);
@@ -9632,10 +9663,12 @@ function SmartSelect({
     if (multiple) {
       const selected = opts.filter((o) => selectedKeys.has(getValue(o)));
       const unselected = opts.filter((o) => !selectedKeys.has(getValue(o)));
-      const filteredRest = inputValue ? unselected.filter(
-        (opt) => getOptionLabel(opt).toLowerCase().includes(inputValue.toLowerCase()) || (getOptionSubLabel?.(opt) ?? "").toLowerCase().includes(inputValue.toLowerCase())
-      ) : unselected;
-      return [...selected, ...filteredRest];
+      if (!inputValue) return [...selected, ...unselected];
+      const q2 = inputValue.toLowerCase();
+      const filteredUnselected = unselected.filter(
+        (opt) => getOptionLabel(opt).toLowerCase().includes(q2) || (getOptionSubLabel?.(opt) ?? "").toLowerCase().includes(q2)
+      ).slice(0, searchThreshold);
+      return [...selected, ...filteredUnselected];
     }
     if (value != null) {
       const selectedLabel = getOptionLabel(value);
@@ -9651,12 +9684,12 @@ function SmartSelect({
     const q = inputValue.toLowerCase();
     return opts.filter(
       (opt) => getOptionLabel(opt).toLowerCase().includes(q) || (getOptionSubLabel?.(opt) ?? "").toLowerCase().includes(q)
-    );
-  }, [filterOptionsProp, multiple, selectedKeys, getValue, getOptionLabel, getOptionSubLabel, value]);
+    ).slice(0, searchThreshold);
+  }, [filterOptionsProp, multiple, selectedKeys, getValue, getOptionLabel, getOptionSubLabel, value, searchThreshold]);
   return /* @__PURE__ */ React108.createElement(
     Autocomplete,
     {
-      options: flatOptionsList,
+      options: displayOptions,
       value: value ?? (multiple ? [] : null),
       onChange: handleChange,
       onInputChange: handleInputChange,
@@ -13567,12 +13600,54 @@ function getStateNameMap(countryCode) {
   }
   return _stateNameCache.get(countryCode);
 }
+var _allCountriesCache = null;
+function getAllCountriesCached() {
+  if (!_allCountriesCache) _allCountriesCache = Country3.getAllCountries();
+  return _allCountriesCache;
+}
+var _allStatesCache = null;
+function getAllStatesCached() {
+  if (!_allStatesCache) {
+    const countryMap = new Map(Country3.getAllCountries().map((c) => [c.isoCode, c.name]));
+    _allStatesCache = State2.getAllStates().map((s2) => ({
+      ...s2,
+      countryName: countryMap.get(s2.countryCode) ?? ""
+    }));
+  }
+  return _allStatesCache;
+}
+var _allCitiesCache = null;
+function getAllCitiesCached() {
+  if (!_allCitiesCache) {
+    const countryMap = new Map(Country3.getAllCountries().map((c) => [c.isoCode, c.name]));
+    const stateMap = new Map(State2.getAllStates().map((s2) => [`${s2.countryCode}:${s2.isoCode}`, s2.name]));
+    _allCitiesCache = City2.getAllCities().map((city) => ({
+      ...city,
+      cityCode: city.name.slice(0, 3),
+      countryName: countryMap.get(city.countryCode) ?? "",
+      stateName: stateMap.get(`${city.countryCode}:${city.stateCode}`) ?? ""
+    }));
+  }
+  return _allCitiesCache;
+}
 function getAllCountries2() {
-  return Country3.getAllCountries();
+  return getAllCountriesCached();
 }
 function getCountryByCode(isoCode) {
   return Country3.getCountryByCode(isoCode) ?? void 0;
 }
+function getCountryByName(name, exact = false) {
+  const q = name.toLowerCase();
+  return getAllCountriesCached().find(
+    (c) => exact ? c.name.toLowerCase() === q : c.name.toLowerCase().includes(q)
+  );
+}
+function getCountriesByName(name, exact = false) {
+  const q = name.toLowerCase();
+  return getAllCountriesCached().filter(
+    (c) => exact ? c.name.toLowerCase() === q : c.name.toLowerCase().includes(q)
+  );
+}
 function getStatesOfCountry(countryCode) {
   const countryName = Country3.getCountryByCode(countryCode)?.name ?? "";
   return State2.getStatesOfCountry(countryCode).map((state) => ({
@@ -13586,6 +13661,18 @@ function getStateByCode(stateCode, countryCode) {
   const countryName = Country3.getCountryByCode(countryCode)?.name ?? "";
   return { ...state, countryName };
 }
+function getStateByName(name, exact = false) {
+  const q = name.toLowerCase();
+  return getAllStatesCached().find(
+    (s2) => exact ? s2.name.toLowerCase() === q : s2.name.toLowerCase().includes(q)
+  );
+}
+function getStatesByName(name, exact = false) {
+  const q = name.toLowerCase();
+  return getAllStatesCached().filter(
+    (s2) => exact ? s2.name.toLowerCase() === q : s2.name.toLowerCase().includes(q)
+  );
+}
 function getCitiesOfState(countryCode, stateCode) {
   const countryName = Country3.getCountryByCode(countryCode)?.name ?? "";
   const stateName = State2.getStateByCodeAndCountry(stateCode, countryCode)?.name ?? "";
@@ -13606,6 +13693,67 @@ function getCitiesOfCountry(countryCode) {
     stateName: stateNameMap.get(city.stateCode) ?? ""
   }));
 }
+function getCityByName(name, exact = false) {
+  const q = name.toLowerCase();
+  return getAllCitiesCached().find(
+    (c) => exact ? c.name.toLowerCase() === q : c.name.toLowerCase().includes(q)
+  );
+}
+function getCitiesByName(name, exact = false) {
+  const q = name.toLowerCase();
+  return getAllCitiesCached().filter(
+    (c) => exact ? c.name.toLowerCase() === q : c.name.toLowerCase().includes(q)
+  );
+}
+
+// lib/utils/useLocationSearch.ts
+import { useState as useState36, useEffect as useEffect31, useRef as useRef34, useCallback as useCallback17 } from "react";
+function useDebounced(searcher, debounceMs) {
+  const [query, setQuery] = useState36("");
+  const [results, setResults] = useState36([]);
+  const timer = useRef34(null);
+  useEffect31(() => () => {
+    if (timer.current) clearTimeout(timer.current);
+  }, []);
+  const search = useCallback17((name) => {
+    setQuery(name);
+    if (timer.current) clearTimeout(timer.current);
+    if (!name.trim()) {
+      setResults([]);
+      return;
+    }
+    timer.current = setTimeout(() => {
+      setResults(searcher(name));
+    }, debounceMs);
+  }, [searcher, debounceMs]);
+  const clear = useCallback17(() => {
+    if (timer.current) clearTimeout(timer.current);
+    setQuery("");
+    setResults([]);
+  }, []);
+  return { results, query, search, clear };
+}
+function useCountriesSearch(debounceMs = 300) {
+  const searcher = useCallback17(
+    (q) => getCountriesByName(q),
+    []
+  );
+  return useDebounced(searcher, debounceMs);
+}
+function useStatesSearch(debounceMs = 300) {
+  const searcher = useCallback17(
+    (q) => getStatesByName(q),
+    []
+  );
+  return useDebounced(searcher, debounceMs);
+}
+function useCitiesSearch(debounceMs = 300) {
+  const searcher = useCallback17(
+    (q) => getCitiesByName(q),
+    []
+  );
+  return useDebounced(searcher, debounceMs);
+}
 export {
   APP_THEMES,
   Accordion,
@@ -13747,11 +13895,20 @@ export {
   workItemIcon_default as WorkItemIcon,
   Zoom,
   getAllCountries2 as getAllCountries,
+  getCitiesByName,
   getCitiesOfCountry,
   getCitiesOfState,
+  getCityByName,
+  getCountriesByName,
   getCountryByCode,
+  getCountryByName,
   getStateByCode,
+  getStateByName,
+  getStatesByName,
   getStatesOfCountry,
   transformLegacyTodos,
-  useRufousTheme
+  useCitiesSearch,
+  useCountriesSearch,
+  useRufousTheme,
+  useStatesSearch
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rufous/ui",
   "private": false,
-  "version": "0.3.19",
+  "version": "0.3.21",
   "type": "module",
   "description": "Experimental: A lightweight React UI component library (Beta)",
   "style": "./dist/main.css",