@jinaan/uikit 0.1.51 → 0.1.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jinaan/uikit",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "description": "Reusable React and Tailwind UI components for Jinaan projects.",
   "license": "UNLICENSED",
   "type": "module",
@@ -42,6 +42,7 @@
     "@radix-ui/react-dialog": "^1.1.4",
     "@radix-ui/react-dropdown-menu": "^2.1.4",
     "@radix-ui/react-label": "^2.1.1",
+    "@radix-ui/react-popover": "^1.1.4",
     "@radix-ui/react-select": "^2.1.4",
     "@radix-ui/react-separator": "^1.1.1",
     "@radix-ui/react-slot": "^1.1.1",

package/src/combobox.tsx

@@ -0,0 +1,252 @@
+import * as PopoverPrimitive from "@radix-ui/react-popover";
+import { CaretDown, MagnifyingGlass } from "@phosphor-icons/react";
+import { useEffect, useMemo, useState, type ReactNode } from "react";
+
+import { Input } from "./input";
+import { Spinner } from "./spinner";
+import { cn } from "./utils";
+
+export interface ComboboxItem {
+  value: string;
+  label: string;
+  /** Secondary line under the label (e.g. an email address). */
+  description?: string;
+  /** Small pill rendered after the label (e.g. "Default"). */
+  badge?: string;
+}
+
+export interface ComboboxProps {
+  items: ComboboxItem[];
+  /** Selected item value; null shows the placeholder. */
+  value: string | null;
+  onValueChange: (item: ComboboxItem) => void;
+  /**
+   * Debounced + trimmed search term (fires after `debounceMs` once the term
+   * reaches `minSearchLength`). Omit to filter `items` client-side instead.
+   */
+  onSearchChange?: (term: string) => void;
+  /** True while an async search is running; shows a centered spinner. */
+  loading?: boolean;
+  /** Minimum search term length before searching/filtering. Default 3. */
+  minSearchLength?: number;
+  /** Debounce window for the search term, in ms. Default 300. */
+  debounceMs?: number;
+  placeholder?: string;
+  searchPlaceholder?: string;
+  /** Shown when a completed search yields no rows. Default "No results found". */
+  emptyMessage?: string;
+  /** Hint below `minSearchLength`; defaults to "Type at least N characters to search". */
+  hintMessage?: string;
+  /** Custom row content; falls back to label + description + badge. */
+  renderItem?: (item: ComboboxItem) => ReactNode;
+  /** Custom selected-value content; falls back to the item label. */
+  renderValue?: (item: ComboboxItem) => ReactNode;
+  className?: string;
+  contentClassName?: string;
+  disabled?: boolean;
+}
+
+/**
+ * Searchable select (Clerk "Select…" parity): an inline secondary trigger that
+ * opens the standard dropdown surface with a search field and item rows.
+ * Searching debounces internally; render `items` either pre-filtered by the
+ * parent (async search through `onSearchChange` + `loading`) or let the
+ * component filter locally when `onSearchChange` is omitted. The content
+ * portals and anchors to the trigger with collision flip, so it overlays —
+ * it never grows the surrounding layout, and it nests safely inside dialogs.
+ */
+export function Combobox({
+  items,
+  value,
+  onValueChange,
+  onSearchChange,
+  loading = false,
+  minSearchLength = 3,
+  debounceMs = 300,
+  placeholder = "Select...",
+  searchPlaceholder = "Search",
+  emptyMessage = "No results found",
+  hintMessage,
+  renderItem,
+  renderValue,
+  className,
+  contentClassName,
+  disabled = false,
+}: ComboboxProps) {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const [debounced, setDebounced] = useState("");
+
+  // Debounce the search term.
+  useEffect(() => {
+    const trimmed = query.trim();
+    const id = setTimeout(() => setDebounced(trimmed), debounceMs);
+    return () => clearTimeout(id);
+  }, [query, debounceMs]);
+
+  // Report settled debounced terms to async search consumers.
+  useEffect(() => {
+    if (!onSearchChange) return;
+    if (open && debounced.length >= minSearchLength) {
+      onSearchChange(debounced);
+    }
+  }, [debounced, open, minSearchLength, onSearchChange]);
+
+  const selected = items.find((item) => item.value === value) ?? null;
+  const trimmed = query.trim();
+  // Empty query → empty message; 1–2 chars → minimum-length hint;
+  // ≥3 chars → spinner while the debounce timer (or parent fetch) is pending.
+  const showHint = trimmed.length > 0 && trimmed.length < minSearchLength;
+  const pending =
+    onSearchChange !== undefined &&
+    trimmed.length >= minSearchLength &&
+    debounced !== trimmed;
+  const hint = hintMessage ?? `Type at least ${minSearchLength} characters to search`;
+
+  // Local mode: filter live; async mode: parent owns items.
+  const filtered = useMemo(() => {
+    if (onSearchChange || trimmed.length === 0) return items;
+    const needle = trimmed.toLowerCase();
+    return items.filter(
+      (item) =>
+        item.label.toLowerCase().includes(needle) ||
+        (item.description ?? "").toLowerCase().includes(needle),
+    );
+  }, [items, trimmed, onSearchChange]);
+
+  const pick = (item: ComboboxItem) => {
+    onValueChange(item);
+    setOpen(false);
+    setQuery("");
+    setDebounced("");
+  };
+
+  const clear = () => {
+    setQuery("");
+    setDebounced("");
+  };
+
+  return (
+    <PopoverPrimitive.Root
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (!next) clear();
+      }}
+    >
+      <PopoverPrimitive.Trigger
+        type="button"
+        disabled={disabled}
+        aria-haspopup="listbox"
+        className={cn(
+          "group btn-fill btn-inner-border btn-interactive flex h-(--control-h-md) w-full items-center justify-between gap-2 rounded-(--control-radius) bg-(--button-secondary-bg) px-(--control-pad-x-sm) font-medium text-fg hover:bg-(--button-surface-hover) active:bg-(--button-surface-active) focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-line-strong",
+          "disabled:cursor-not-allowed disabled:opacity-50",
+          className,
+        )}
+      >
+        {selected ? (
+          renderValue ? (
+            renderValue(selected)
+          ) : (
+            <span className="min-w-0 truncate">{selected.label}</span>
+          )
+        ) : (
+          <span className="font-normal text-muted">{placeholder}</span>
+        )}
+        <CaretDown
+          aria-hidden
+          className="size-3.5 shrink-0 text-muted transition-transform duration-200 ease-out group-data-[state=open]:rotate-180 motion-reduce:transition-none"
+        />
+      </PopoverPrimitive.Trigger>
+      <PopoverPrimitive.Portal>
+        <PopoverPrimitive.Content
+          role="listbox"
+          aria-label={placeholder}
+          align="start"
+          sideOffset={4}
+          className={cn(
+            "menu-surface btn-inner-border z-50 overflow-hidden rounded-lg border border-line bg-(--button-secondary-bg) p-1",
+            "w-(--radix-popper-anchor-width)",
+            "data-[state=open]:animate-in data-[state=closed]:animate-out",
+            "data-[state=open]:fade-in-0 data-[state=closed]:fade-out-0",
+            "data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95",
+            "duration-150 ease-out",
+            contentClassName,
+          )}
+          onKeyDown={(event) => {
+            // Escape closes the combobox, not a surrounding dialog.
+            if (event.key === "Escape") {
+              event.stopPropagation();
+              setOpen(false);
+              clear();
+            }
+          }}
+        >
+          <div className="pb-1">
+            <Input
+              value={query}
+              onChange={(event) => setQuery(event.target.value)}
+              onClear={() => clear()}
+              placeholder={searchPlaceholder}
+              aria-label={searchPlaceholder}
+              leadingIcon={<MagnifyingGlass className="size-3.5" />}
+              size="sm"
+              className="h-(--control-h-xs) border-0 bg-(--combobox-search-bg) focus-visible:border-muted focus-visible:ring-0"
+            />
+          </div>
+          <div className="max-h-64 overflow-y-auto" role="presentation">
+            {showHint ? (
+              <p className="px-2 py-3 text-center text-sm text-muted">{hint}</p>
+            ) : filtered.length > 0 ? (
+              filtered.map((item) => (
+                <button
+                  key={item.value}
+                  type="button"
+                  role="option"
+                  aria-selected={item.value === value}
+                  onClick={() => pick(item)}
+                  className={cn(
+                    "flex w-full items-center gap-3 rounded-lg px-2 py-2 text-left transition-colors",
+                    item.value === value
+                      ? "bg-(--button-surface-active)"
+                      : "hover:bg-(--button-surface-hover)",
+                  )}
+                >
+                  {renderItem ? (
+                    renderItem(item)
+                  ) : (
+                    <span className="min-w-0">
+                      <span className="flex items-center gap-1.5">
+                        <span className="truncate text-sm font-medium text-fg">
+                          {item.label}
+                        </span>
+                        {item.badge && (
+                          <span className="rounded bg-elevated px-1.5 py-0.5 text-[11px] text-muted">
+                            {item.badge}
+                          </span>
+                        )}
+                      </span>
+                      {item.description && (
+                        <span className="block truncate text-[13px] text-muted">
+                          {item.description}
+                        </span>
+                      )}
+                    </span>
+                  )}
+                </button>
+              ))
+            ) : loading || pending ? (
+              <div className="flex justify-center py-4">
+                <Spinner className="size-5 text-muted" />
+              </div>
+            ) : (
+              <p className="px-2 py-3 text-center text-sm text-muted">
+                {emptyMessage}
+              </p>
+            )}
+          </div>
+        </PopoverPrimitive.Content>
+      </PopoverPrimitive.Portal>
+    </PopoverPrimitive.Root>
+  );
+}

package/src/index.ts

@@ -7,6 +7,7 @@ export * from "./card";
 export * from "./checkbox";
 export * from "./choice-dialog";
 export * from "./code-block";
+export * from "./combobox";
 export * from "./data-table";
 export * from "./dialog";
 export * from "./dropdown-menu";

package/styles.css

@@ -100,6 +100,7 @@
   --input-border-hover: #c7c7cf;
   --input-border-focus: var(--primary);
   --input-bg-disabled: #f6f6f7;
+  --combobox-search-bg: rgb(245, 245, 246);
 
   /* Button surfaces. */
   --button-primary-bg: var(--primary);
@@ -213,6 +214,7 @@
   --input-border-hover: #4d4d5a;
   --input-border-focus: var(--primary-hover);
   --input-bg-disabled: #26262c;
+  --combobox-search-bg: rgb(32, 32, 35);
 
   --button-primary-bg: var(--primary);
   --button-primary-fg: var(--primary-fg);