@zentauri-ui/zentauri-components 1.4.3 → 1.4.5

package/README.md

@@ -58,6 +58,7 @@ Import static primitives from `@zentauri-ui/zentauri-components/ui/<subpath>` wh
 | Modal          | `modal`               | `modal/animated`                     |
 | Pagination     | `pagination`          | —                                    |
 | Progress       | `progress`            | `progress/animated`                  |
+| Search         | `search`              | -                                    |
 | Select         | `select`              | —                                    |
 | Skeleton       | `skeleton`            | `skeleton/animated`                  |
 | Slider         | `slider`              | —                                    |
@@ -283,16 +284,16 @@ Which UI folders are valid for `add` is driven by **`cli/registry.json`**: a gen
 Call the published binary by name after the package (recommended so `npx` does not treat the first word as a shell command):
 
 ```bash
-npx @zentauri-ui/zentauri-components zentauri-components init
-npx @zentauri-ui/zentauri-components zentauri-components add buttons inputs
-npx @zentauri-ui/zentauri-components zentauri-components -h
+npx @zentauri-ui/zentauri-components init
+npx @zentauri-ui/zentauri-components add buttons inputs
+npx @zentauri-ui/zentauri-components -h
 ```
 
 **Hooks only** (copy `src/hooks/<name>` into your app, plus sibling hook dependencies such as `useMediaQuery` when needed):
 
 ```bash
-npx @zentauri-ui/zentauri-components zentauri-components add hook useWindowSize
-npx @zentauri-ui/zentauri-components zentauri-components add hook useToggle useDebouncedValue
+npx @zentauri-ui/zentauri-components add hook useWindowSize
+npx @zentauri-ui/zentauri-components add hook useToggle useDebouncedValue
 ```
 
 The **`zentauri-ui`** binary is the same entry as **`zentauri-components`**. If `npx` still mis-resolves, pin the package:

package/cli/index.mjs

@@ -165,8 +165,8 @@ Use hooks from the package without copying (after npm install):
   import { useWindowSize } from "@zentauri-ui/zentauri-components/hooks/useWindowSize";
 
 Published package:
-  npx @zentauri-ui/zentauri-components zentauri-components init
-  npx @zentauri-ui/zentauri-components zentauri-components add accordion buttons inputs
+  npx @zentauri-ui/zentauri-components init
+  npx @zentauri-ui/zentauri-components add accordion buttons inputs
 
 If npx does not pick the right binary:
   npx --yes --package=@zentauri-ui/zentauri-components zentauri-components init

package/cli/registry.json

@@ -18,6 +18,7 @@
     "modal",
     "pagination",
     "progress",
+    "search",
     "select",
     "skeleton",
     "slider",

package/dist/ui/search/filter-search-suggestions.d.ts

@@ -0,0 +1,15 @@
+import type { SearchFilterable } from "./types";
+export type FilterSearchSuggestionsOptions = {
+    /** Maximum number of matches returned. */
+    maxResults?: number;
+};
+/**
+ * Returns items whose label, description, href, or keywords contain the query (case-insensitive).
+ * Whitespace-only query matches no items.
+ */
+export declare function filterSearchSuggestions<T extends SearchFilterable>({ query, items, options, }: {
+    query: string;
+    items: readonly T[];
+    options?: FilterSearchSuggestionsOptions;
+}): T[];
+//# sourceMappingURL=filter-search-suggestions.d.ts.map

package/dist/ui/search/filter-search-suggestions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-search-suggestions.d.ts","sourceRoot":"","sources":["../../../src/ui/search/filter-search-suggestions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD,MAAM,MAAM,8BAA8B,GAAG;IAC3C,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,gBAAgB,EAAE,EAClE,KAAK,EACL,KAAK,EACL,OAA4B,GAC7B,EAAE;IACD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,8BAA8B,CAAC;CAC1C,GAAG,CAAC,EAAE,CAuBN"}

package/dist/ui/search/index.d.ts

@@ -0,0 +1,7 @@
+export { SearchBar } from "./search-bar";
+export { SearchSuggestionList } from "./search-suggestion-list";
+export { searchSuggestionOptionDomId } from "./search-suggestion-utils";
+export { filterSearchSuggestions } from "./filter-search-suggestions";
+export type { SearchBarProps, SearchSuggestionItem, SearchSuggestionListProps, SearchFilterable, } from "./types";
+export type { FilterSearchSuggestionsOptions } from "./filter-search-suggestions";
+//# sourceMappingURL=index.d.ts.map

package/dist/ui/search/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ui/search/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,YAAY,EACV,cAAc,EACd,oBAAoB,EACpB,yBAAyB,EACzB,gBAAgB,GACjB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/ui/search/search-bar.d.ts

@@ -0,0 +1,6 @@
+import type { SearchBarProps } from "./types";
+export declare const SearchBar: {
+    ({ value, onValueChange, leadingSlot, className, inputClassName, appearance, inputSize, ring, id, onChange, disabled, type, comboboxListboxId, comboboxActiveOptionId, comboboxExpanded, ref, ...rest }: SearchBarProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+//# sourceMappingURL=search-bar.d.ts.map

package/dist/ui/search/search-bar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-bar.d.ts","sourceRoot":"","sources":["../../../src/ui/search/search-bar.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,eAAO,MAAM,SAAS;6MAmBjB,cAAc;;CAoDlB,CAAA"}

package/dist/ui/search/search-suggestion-list.d.ts

@@ -0,0 +1,6 @@
+import type { SearchSuggestionListProps } from "./types";
+export declare function SearchSuggestionList({ items, onSelect, activeId, onActiveIdChange, listboxId, className, listClassName, emptyLabel, }: SearchSuggestionListProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace SearchSuggestionList {
+    var displayName: string;
+}
+//# sourceMappingURL=search-suggestion-list.d.ts.map

package/dist/ui/search/search-suggestion-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-suggestion-list.d.ts","sourceRoot":"","sources":["../../../src/ui/search/search-suggestion-list.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAKzD,wBAAgB,oBAAoB,CAAC,EACnC,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,gBAAgB,EAChB,SAAS,EACT,SAAS,EACT,aAAa,EACb,UAAU,GACX,EAAE,yBAAyB,2CAsE3B;yBA/Ee,oBAAoB"}

package/dist/ui/search/search-suggestion-utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Builds a stable DOM id for a listbox option so `aria-activedescendant` on the combobox
+ * input can reference it. Safe for href-like `itemId` strings.
+ */
+export declare function searchSuggestionOptionDomId(listboxId: string, itemId: string): string;
+//# sourceMappingURL=search-suggestion-utils.d.ts.map

package/dist/ui/search/search-suggestion-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-suggestion-utils.d.ts","sourceRoot":"","sources":["../../../src/ui/search/search-suggestion-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGrF"}

package/dist/ui/search/types.d.ts

@@ -0,0 +1,44 @@
+import type { InputHTMLAttributes, ReactNode, Ref } from "react";
+import type { VariantProps } from "class-variance-authority";
+import type { inputVariants } from "../inputs/variants";
+export type SearchBarProps = Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "children" | "role"> & {
+    value: string;
+    onValueChange?: (value: string) => void;
+    leadingSlot?: ReactNode;
+    inputClassName?: string;
+    appearance?: VariantProps<typeof inputVariants>["appearance"];
+    inputSize?: VariantProps<typeof inputVariants>["size"];
+    ring?: VariantProps<typeof inputVariants>["ring"];
+    /** When set, the input exposes combobox semantics wired to a `role="listbox"` with this id. */
+    comboboxListboxId?: string;
+    /** Element id of the active option (from `searchSuggestionOptionDomId`) for `aria-activedescendant`. */
+    comboboxActiveOptionId?: string;
+    /** Whether the suggestion list is visibly expanded (controls `aria-expanded`). */
+    comboboxExpanded?: boolean;
+    ref?: Ref<HTMLInputElement>;
+};
+export type SearchSuggestionItem = {
+    id: string;
+    label: string;
+    description?: string;
+    group?: string;
+};
+export type SearchSuggestionListProps = {
+    items: readonly SearchSuggestionItem[];
+    onSelect: (id: string) => void;
+    activeId?: string;
+    onActiveIdChange?: (id: string | undefined) => void;
+    /** Pass the same id as `comboboxListboxId` on `SearchBar` for ARIA wiring. */
+    listboxId?: string;
+    className?: string;
+    listClassName?: string;
+    emptyLabel?: ReactNode;
+};
+export type SearchFilterable = {
+    id: string;
+    label: string;
+    description?: string;
+    keywords?: readonly string[];
+    href?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/ui/search/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/ui/search/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAEjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,MAAM,cAAc,GAAG,IAAI,CAC/B,mBAAmB,CAAC,gBAAgB,CAAC,EACrC,MAAM,GAAG,UAAU,GAAG,MAAM,CAC7B,GAAG;IACF,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,YAAY,CAAC,OAAO,aAAa,CAAC,CAAC,YAAY,CAAC,CAAC;IAC9D,SAAS,CAAC,EAAE,YAAY,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;IACvD,IAAI,CAAC,EAAE,YAAY,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;IAClD,+FAA+F;IAC/F,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wGAAwG;IACxG,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,GAAG,CAAC,EAAE,GAAG,CAAC,gBAAgB,CAAC,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACvC,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IACpD,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,SAAS,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC"}

package/dist/ui/search.js

@@ -0,0 +1,195 @@
+"use client";
+'use strict';
+
+var chunkQZKMFSH5_js = require('../chunk-QZKMFSH5.js');
+var chunkUOZYPWDZ_js = require('../chunk-UOZYPWDZ.js');
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+var SearchBar = function SearchBar2({
+  value,
+  onValueChange,
+  leadingSlot,
+  className,
+  inputClassName,
+  appearance = "default",
+  inputSize = "md",
+  ring = true,
+  id,
+  onChange,
+  disabled,
+  type,
+  comboboxListboxId,
+  comboboxActiveOptionId,
+  comboboxExpanded,
+  ref,
+  ...rest
+}) {
+  const generatedId = react.useId();
+  const controlId = id ?? generatedId;
+  const combobox = Boolean(comboboxListboxId);
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      "data-slot": "search-bar",
+      className: chunkUOZYPWDZ_js.cn("relative flex w-full min-w-0 items-center", className),
+      children: [
+        leadingSlot ? /* @__PURE__ */ jsxRuntime.jsx(
+          "span",
+          {
+            className: "pointer-events-none absolute left-3 top-1/2 z-1 flex -translate-y-1/2 text-slate-400 [&_svg]:size-4",
+            "aria-hidden": true,
+            children: leadingSlot
+          }
+        ) : null,
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "input",
+          {
+            ref,
+            id: controlId,
+            type: type ?? "search",
+            autoComplete: "off",
+            spellCheck: false,
+            disabled,
+            value,
+            "data-slot": "search-bar-input",
+            className: chunkUOZYPWDZ_js.cn(
+              chunkQZKMFSH5_js.inputVariants({ appearance, size: inputSize, ring, as: "input" }),
+              leadingSlot ? "pl-10" : null,
+              inputClassName
+            ),
+            onChange: (event) => {
+              onChange?.(event);
+              onValueChange?.(event.target.value);
+            },
+            ...combobox ? {
+              role: "combobox",
+              "aria-autocomplete": "list",
+              "aria-controls": comboboxListboxId,
+              "aria-expanded": comboboxExpanded ?? false,
+              ...comboboxActiveOptionId ? { "aria-activedescendant": comboboxActiveOptionId } : {}
+            } : {},
+            ...rest
+          }
+        )
+      ]
+    }
+  );
+};
+SearchBar.displayName = "SearchBar";
+
+// src/ui/search/search-suggestion-utils.ts
+function searchSuggestionOptionDomId(listboxId, itemId) {
+  const safe = itemId.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return `${listboxId}_opt_${safe}`;
+}
+var rowClassName = "flex w-full flex-col gap-0.5 rounded-lg px-3 py-2.5 text-left text-sm transition-colors hover:bg-white/5 focus-visible:bg-white/5 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-400/50";
+function SearchSuggestionList({
+  items,
+  onSelect,
+  activeId,
+  onActiveIdChange,
+  listboxId,
+  className,
+  listClassName,
+  emptyLabel
+}) {
+  if (items.length === 0) {
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        "data-slot": "search-suggestion-list-empty",
+        className: chunkUOZYPWDZ_js.cn("px-1 py-6 text-center text-sm text-slate-500", className),
+        children: emptyLabel ?? "No matches."
+      }
+    );
+  }
+  let lastGroup;
+  const useListbox = Boolean(listboxId);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "nav",
+    {
+      "data-slot": "search-suggestion-list",
+      "aria-label": "Search results",
+      className: chunkUOZYPWDZ_js.cn("flex max-h-[min(50vh,360px)] flex-col gap-1 overflow-y-auto pr-1", className),
+      children: /* @__PURE__ */ jsxRuntime.jsx(
+        "div",
+        {
+          ...useListbox ? {
+            id: listboxId,
+            role: "listbox"
+          } : {},
+          className: chunkUOZYPWDZ_js.cn("flex flex-col gap-0.5", listClassName),
+          children: items.map((item) => {
+            const showGroup = item.group && item.group !== lastGroup;
+            if (item.group) {
+              lastGroup = item.group;
+            }
+            const isActive = activeId === item.id;
+            const optionDomId = useListbox && listboxId ? searchSuggestionOptionDomId(listboxId, item.id) : void 0;
+            return /* @__PURE__ */ jsxRuntime.jsxs(react.Fragment, { children: [
+              showGroup ? /* @__PURE__ */ jsxRuntime.jsx(
+                "div",
+                {
+                  role: "presentation",
+                  className: "sticky top-0 z-1 bg-slate-950/95 px-2 pb-1 pt-2 text-xs font-semibold uppercase tracking-wide text-slate-500 backdrop-blur-sm",
+                  children: item.group
+                }
+              ) : null,
+              /* @__PURE__ */ jsxRuntime.jsxs(
+                "button",
+                {
+                  type: "button",
+                  id: optionDomId,
+                  role: useListbox ? "option" : void 0,
+                  "aria-selected": useListbox ? isActive : void 0,
+                  "data-active": isActive ? "" : void 0,
+                  className: chunkUOZYPWDZ_js.cn(rowClassName, isActive ? "bg-white/5" : null),
+                  onMouseEnter: () => onActiveIdChange?.(item.id),
+                  onFocus: () => onActiveIdChange?.(item.id),
+                  onClick: () => onSelect(item.id),
+                  children: [
+                    /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-medium text-slate-100", children: item.label }),
+                    item.description ? /* @__PURE__ */ jsxRuntime.jsx("span", { className: "truncate text-xs text-slate-500", children: item.description }) : null
+                  ]
+                }
+              )
+            ] }, item.id);
+          })
+        }
+      )
+    }
+  );
+}
+SearchSuggestionList.displayName = "SearchSuggestionList";
+
+// src/ui/search/filter-search-suggestions.ts
+function filterSearchSuggestions({
+  query,
+  items,
+  options = { maxResults: 20 }
+}) {
+  const maxResults = options.maxResults ?? 20;
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) {
+    return [];
+  }
+  const matches = [];
+  for (const item of items) {
+    const isMatch = item.label.toLowerCase().includes(normalized) || item.description?.toLowerCase().includes(normalized) || item.href?.toLowerCase().includes(normalized) || item.keywords?.some((k) => k.toLowerCase().includes(normalized));
+    if (isMatch) {
+      matches.push(item);
+      if (matches.length >= maxResults || maxResults <= 0) {
+        break;
+      }
+    }
+  }
+  return matches;
+}
+
+exports.SearchBar = SearchBar;
+exports.SearchSuggestionList = SearchSuggestionList;
+exports.filterSearchSuggestions = filterSearchSuggestions;
+exports.searchSuggestionOptionDomId = searchSuggestionOptionDomId;
+//# sourceMappingURL=search.js.map
+//# sourceMappingURL=search.js.map

package/dist/ui/search.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ui/search/search-bar.tsx","../../src/ui/search/search-suggestion-utils.ts","../../src/ui/search/search-suggestion-list.tsx","../../src/ui/search/filter-search-suggestions.ts"],"names":["SearchBar","useId","jsxs","cn","jsx","inputVariants","Fragment"],"mappings":"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","file":"search.js","sourcesContent":["\"use client\";\n\nimport { forwardRef, useId } from \"react\";\n\nimport { cn } from \"../../lib/utils\";\nimport { inputVariants } from \"../inputs/variants\";\n\nimport type { SearchBarProps } from \"./types\";\n\nexport const SearchBar = function SearchBar(\n  {\n    value,\n    onValueChange,\n    leadingSlot,\n    className,\n    inputClassName,\n    appearance = \"default\",\n    inputSize = \"md\",\n    ring = true,\n    id,\n    onChange,\n    disabled,\n    type,\n    comboboxListboxId,\n    comboboxActiveOptionId,\n    comboboxExpanded,\n    ref,\n    ...rest\n  }: SearchBarProps,\n) {\n  const generatedId = useId();\n  const controlId = id ?? generatedId;\n  const combobox = Boolean(comboboxListboxId);\n\n  return (\n    <div\n      data-slot=\"search-bar\"\n      className={cn(\"relative flex w-full min-w-0 items-center\", className)}\n    >\n      {leadingSlot ? (\n        <span\n          className=\"pointer-events-none absolute left-3 top-1/2 z-1 flex -translate-y-1/2 text-slate-400 [&_svg]:size-4\"\n          aria-hidden\n        >\n          {leadingSlot}\n        </span>\n      ) : null}\n      <input\n        ref={ref}\n        id={controlId}\n        type={type ?? \"search\"}\n        autoComplete=\"off\"\n        spellCheck={false}\n        disabled={disabled}\n        value={value}\n        data-slot=\"search-bar-input\"\n        className={cn(\n          inputVariants({ appearance, size: inputSize, ring, as: \"input\" }),\n          leadingSlot ? \"pl-10\" : null,\n          inputClassName,\n        )}\n        onChange={(event) => {\n          onChange?.(event);\n          onValueChange?.(event.target.value);\n        }}\n        {...(combobox\n          ? {\n              role: \"combobox\" as const,\n              \"aria-autocomplete\": \"list\" as const,\n              \"aria-controls\": comboboxListboxId,\n              \"aria-expanded\": comboboxExpanded ?? false,\n              ...(comboboxActiveOptionId\n                ? { \"aria-activedescendant\": comboboxActiveOptionId }\n                : {}),\n            }\n          : {})}\n        {...rest}\n      />\n    </div>\n  );\n}\n\nSearchBar.displayName = \"SearchBar\";\n","/**\n * Builds a stable DOM id for a listbox option so `aria-activedescendant` on the combobox\n * input can reference it. Safe for href-like `itemId` strings.\n */\nexport function searchSuggestionOptionDomId(listboxId: string, itemId: string): string {\n  const safe = itemId.replace(/[^a-zA-Z0-9_-]/g, \"_\");\n  return `${listboxId}_opt_${safe}`;\n}\n","\"use client\";\n\nimport { Fragment } from \"react\";\n\nimport { cn } from \"../../lib/utils\";\nimport { searchSuggestionOptionDomId } from \"./search-suggestion-utils\";\n\nimport type { SearchSuggestionListProps } from \"./types\";\n\nconst rowClassName =\n  \"flex w-full flex-col gap-0.5 rounded-lg px-3 py-2.5 text-left text-sm transition-colors hover:bg-white/5 focus-visible:bg-white/5 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-400/50\";\n\nexport function SearchSuggestionList({\n  items,\n  onSelect,\n  activeId,\n  onActiveIdChange,\n  listboxId,\n  className,\n  listClassName,\n  emptyLabel,\n}: SearchSuggestionListProps) {\n  if (items.length === 0) {\n    return (\n      <div\n        data-slot=\"search-suggestion-list-empty\"\n        className={cn(\"px-1 py-6 text-center text-sm text-slate-500\", className)}\n      >\n        {emptyLabel ?? \"No matches.\"}\n      </div>\n    );\n  }\n\n  let lastGroup: string | undefined;\n  const useListbox = Boolean(listboxId);\n\n  return (\n    <nav\n      data-slot=\"search-suggestion-list\"\n      aria-label=\"Search results\"\n      className={cn(\"flex max-h-[min(50vh,360px)] flex-col gap-1 overflow-y-auto pr-1\", className)}\n    >\n      <div\n        {...(useListbox\n          ? {\n              id: listboxId,\n              role: \"listbox\" as const,\n            }\n          : {})}\n        className={cn(\"flex flex-col gap-0.5\", listClassName)}\n      >\n        {items.map((item) => {\n          const showGroup = item.group && item.group !== lastGroup;\n          if (item.group) {\n            lastGroup = item.group;\n          }\n          const isActive = activeId === item.id;\n          const optionDomId =\n            useListbox && listboxId ? searchSuggestionOptionDomId(listboxId, item.id) : undefined;\n          return (\n            <Fragment key={item.id}>\n              {showGroup ? (\n                <div\n                  role=\"presentation\"\n                  className=\"sticky top-0 z-1 bg-slate-950/95 px-2 pb-1 pt-2 text-xs font-semibold uppercase tracking-wide text-slate-500 backdrop-blur-sm\"\n                >\n                  {item.group}\n                </div>\n              ) : null}\n              <button\n                type=\"button\"\n                id={optionDomId}\n                role={useListbox ? \"option\" : undefined}\n                aria-selected={useListbox ? isActive : undefined}\n                data-active={isActive ? \"\" : undefined}\n                className={cn(rowClassName, isActive ? \"bg-white/5\" : null)}\n                onMouseEnter={() => onActiveIdChange?.(item.id)}\n                onFocus={() => onActiveIdChange?.(item.id)}\n                onClick={() => onSelect(item.id)}\n              >\n                <span className=\"font-medium text-slate-100\">{item.label}</span>\n                {item.description ? (\n                  <span className=\"truncate text-xs text-slate-500\">{item.description}</span>\n                ) : null}\n              </button>\n            </Fragment>\n          );\n        })}\n      </div>\n    </nav>\n  );\n}\n\nSearchSuggestionList.displayName = \"SearchSuggestionList\";\n\n","import type { SearchFilterable } from \"./types\";\n\nexport type FilterSearchSuggestionsOptions = {\n  /** Maximum number of matches returned. */\n  maxResults?: number;\n};\n\n/**\n * Returns items whose label, description, href, or keywords contain the query (case-insensitive).\n * Whitespace-only query matches no items.\n */\nexport function filterSearchSuggestions<T extends SearchFilterable>({\n  query,\n  items,\n  options = { maxResults: 20 },\n}: {\n  query: string;\n  items: readonly T[];\n  options?: FilterSearchSuggestionsOptions;\n}): T[] {\n  const maxResults = options.maxResults ?? 20;\n  const normalized = query.trim().toLowerCase();\n  if (!normalized) {\n    return [];\n  }\n\n  const matches: T[] = [];\n  for (const item of items) {\n    const isMatch =\n      item.label.toLowerCase().includes(normalized) ||\n      (item.description?.toLowerCase().includes(normalized)) ||\n      (item.href?.toLowerCase().includes(normalized)) ||\n      (item.keywords?.some((k) => k.toLowerCase().includes(normalized)));\n\n    if (isMatch) {\n      matches.push(item);\n      if (matches.length >= maxResults || maxResults <= 0) {\n        break;\n      }\n    }\n  }\n  return matches;\n}\n"]}

package/dist/ui/search.mjs

@@ -0,0 +1,190 @@
+"use client";
+import { inputVariants } from '../chunk-AOEI4V3W.mjs';
+import { cn } from '../chunk-DFEZH7TC.mjs';
+import { useId, Fragment } from 'react';
+import { jsxs, jsx } from 'react/jsx-runtime';
+
+var SearchBar = function SearchBar2({
+  value,
+  onValueChange,
+  leadingSlot,
+  className,
+  inputClassName,
+  appearance = "default",
+  inputSize = "md",
+  ring = true,
+  id,
+  onChange,
+  disabled,
+  type,
+  comboboxListboxId,
+  comboboxActiveOptionId,
+  comboboxExpanded,
+  ref,
+  ...rest
+}) {
+  const generatedId = useId();
+  const controlId = id ?? generatedId;
+  const combobox = Boolean(comboboxListboxId);
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-slot": "search-bar",
+      className: cn("relative flex w-full min-w-0 items-center", className),
+      children: [
+        leadingSlot ? /* @__PURE__ */ jsx(
+          "span",
+          {
+            className: "pointer-events-none absolute left-3 top-1/2 z-1 flex -translate-y-1/2 text-slate-400 [&_svg]:size-4",
+            "aria-hidden": true,
+            children: leadingSlot
+          }
+        ) : null,
+        /* @__PURE__ */ jsx(
+          "input",
+          {
+            ref,
+            id: controlId,
+            type: type ?? "search",
+            autoComplete: "off",
+            spellCheck: false,
+            disabled,
+            value,
+            "data-slot": "search-bar-input",
+            className: cn(
+              inputVariants({ appearance, size: inputSize, ring, as: "input" }),
+              leadingSlot ? "pl-10" : null,
+              inputClassName
+            ),
+            onChange: (event) => {
+              onChange?.(event);
+              onValueChange?.(event.target.value);
+            },
+            ...combobox ? {
+              role: "combobox",
+              "aria-autocomplete": "list",
+              "aria-controls": comboboxListboxId,
+              "aria-expanded": comboboxExpanded ?? false,
+              ...comboboxActiveOptionId ? { "aria-activedescendant": comboboxActiveOptionId } : {}
+            } : {},
+            ...rest
+          }
+        )
+      ]
+    }
+  );
+};
+SearchBar.displayName = "SearchBar";
+
+// src/ui/search/search-suggestion-utils.ts
+function searchSuggestionOptionDomId(listboxId, itemId) {
+  const safe = itemId.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return `${listboxId}_opt_${safe}`;
+}
+var rowClassName = "flex w-full flex-col gap-0.5 rounded-lg px-3 py-2.5 text-left text-sm transition-colors hover:bg-white/5 focus-visible:bg-white/5 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-400/50";
+function SearchSuggestionList({
+  items,
+  onSelect,
+  activeId,
+  onActiveIdChange,
+  listboxId,
+  className,
+  listClassName,
+  emptyLabel
+}) {
+  if (items.length === 0) {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        "data-slot": "search-suggestion-list-empty",
+        className: cn("px-1 py-6 text-center text-sm text-slate-500", className),
+        children: emptyLabel ?? "No matches."
+      }
+    );
+  }
+  let lastGroup;
+  const useListbox = Boolean(listboxId);
+  return /* @__PURE__ */ jsx(
+    "nav",
+    {
+      "data-slot": "search-suggestion-list",
+      "aria-label": "Search results",
+      className: cn("flex max-h-[min(50vh,360px)] flex-col gap-1 overflow-y-auto pr-1", className),
+      children: /* @__PURE__ */ jsx(
+        "div",
+        {
+          ...useListbox ? {
+            id: listboxId,
+            role: "listbox"
+          } : {},
+          className: cn("flex flex-col gap-0.5", listClassName),
+          children: items.map((item) => {
+            const showGroup = item.group && item.group !== lastGroup;
+            if (item.group) {
+              lastGroup = item.group;
+            }
+            const isActive = activeId === item.id;
+            const optionDomId = useListbox && listboxId ? searchSuggestionOptionDomId(listboxId, item.id) : void 0;
+            return /* @__PURE__ */ jsxs(Fragment, { children: [
+              showGroup ? /* @__PURE__ */ jsx(
+                "div",
+                {
+                  role: "presentation",
+                  className: "sticky top-0 z-1 bg-slate-950/95 px-2 pb-1 pt-2 text-xs font-semibold uppercase tracking-wide text-slate-500 backdrop-blur-sm",
+                  children: item.group
+                }
+              ) : null,
+              /* @__PURE__ */ jsxs(
+                "button",
+                {
+                  type: "button",
+                  id: optionDomId,
+                  role: useListbox ? "option" : void 0,
+                  "aria-selected": useListbox ? isActive : void 0,
+                  "data-active": isActive ? "" : void 0,
+                  className: cn(rowClassName, isActive ? "bg-white/5" : null),
+                  onMouseEnter: () => onActiveIdChange?.(item.id),
+                  onFocus: () => onActiveIdChange?.(item.id),
+                  onClick: () => onSelect(item.id),
+                  children: [
+                    /* @__PURE__ */ jsx("span", { className: "font-medium text-slate-100", children: item.label }),
+                    item.description ? /* @__PURE__ */ jsx("span", { className: "truncate text-xs text-slate-500", children: item.description }) : null
+                  ]
+                }
+              )
+            ] }, item.id);
+          })
+        }
+      )
+    }
+  );
+}
+SearchSuggestionList.displayName = "SearchSuggestionList";
+
+// src/ui/search/filter-search-suggestions.ts
+function filterSearchSuggestions({
+  query,
+  items,
+  options = { maxResults: 20 }
+}) {
+  const maxResults = options.maxResults ?? 20;
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) {
+    return [];
+  }
+  const matches = [];
+  for (const item of items) {
+    const isMatch = item.label.toLowerCase().includes(normalized) || item.description?.toLowerCase().includes(normalized) || item.href?.toLowerCase().includes(normalized) || item.keywords?.some((k) => k.toLowerCase().includes(normalized));
+    if (isMatch) {
+      matches.push(item);
+      if (matches.length >= maxResults || maxResults <= 0) {
+        break;
+      }
+    }
+  }
+  return matches;
+}
+
+export { SearchBar, SearchSuggestionList, filterSearchSuggestions, searchSuggestionOptionDomId };
+//# sourceMappingURL=search.mjs.map
+//# sourceMappingURL=search.mjs.map

package/dist/ui/search.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ui/search/search-bar.tsx","../../src/ui/search/search-suggestion-utils.ts","../../src/ui/search/search-suggestion-list.tsx","../../src/ui/search/filter-search-suggestions.ts"],"names":["SearchBar","jsx","jsxs"],"mappings":"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","file":"search.mjs","sourcesContent":["\"use client\";\n\nimport { forwardRef, useId } from \"react\";\n\nimport { cn } from \"../../lib/utils\";\nimport { inputVariants } from \"../inputs/variants\";\n\nimport type { SearchBarProps } from \"./types\";\n\nexport const SearchBar = function SearchBar(\n  {\n    value,\n    onValueChange,\n    leadingSlot,\n    className,\n    inputClassName,\n    appearance = \"default\",\n    inputSize = \"md\",\n    ring = true,\n    id,\n    onChange,\n    disabled,\n    type,\n    comboboxListboxId,\n    comboboxActiveOptionId,\n    comboboxExpanded,\n    ref,\n    ...rest\n  }: SearchBarProps,\n) {\n  const generatedId = useId();\n  const controlId = id ?? generatedId;\n  const combobox = Boolean(comboboxListboxId);\n\n  return (\n    <div\n      data-slot=\"search-bar\"\n      className={cn(\"relative flex w-full min-w-0 items-center\", className)}\n    >\n      {leadingSlot ? (\n        <span\n          className=\"pointer-events-none absolute left-3 top-1/2 z-1 flex -translate-y-1/2 text-slate-400 [&_svg]:size-4\"\n          aria-hidden\n        >\n          {leadingSlot}\n        </span>\n      ) : null}\n      <input\n        ref={ref}\n        id={controlId}\n        type={type ?? \"search\"}\n        autoComplete=\"off\"\n        spellCheck={false}\n        disabled={disabled}\n        value={value}\n        data-slot=\"search-bar-input\"\n        className={cn(\n          inputVariants({ appearance, size: inputSize, ring, as: \"input\" }),\n          leadingSlot ? \"pl-10\" : null,\n          inputClassName,\n        )}\n        onChange={(event) => {\n          onChange?.(event);\n          onValueChange?.(event.target.value);\n        }}\n        {...(combobox\n          ? {\n              role: \"combobox\" as const,\n              \"aria-autocomplete\": \"list\" as const,\n              \"aria-controls\": comboboxListboxId,\n              \"aria-expanded\": comboboxExpanded ?? false,\n              ...(comboboxActiveOptionId\n                ? { \"aria-activedescendant\": comboboxActiveOptionId }\n                : {}),\n            }\n          : {})}\n        {...rest}\n      />\n    </div>\n  );\n}\n\nSearchBar.displayName = \"SearchBar\";\n","/**\n * Builds a stable DOM id for a listbox option so `aria-activedescendant` on the combobox\n * input can reference it. Safe for href-like `itemId` strings.\n */\nexport function searchSuggestionOptionDomId(listboxId: string, itemId: string): string {\n  const safe = itemId.replace(/[^a-zA-Z0-9_-]/g, \"_\");\n  return `${listboxId}_opt_${safe}`;\n}\n","\"use client\";\n\nimport { Fragment } from \"react\";\n\nimport { cn } from \"../../lib/utils\";\nimport { searchSuggestionOptionDomId } from \"./search-suggestion-utils\";\n\nimport type { SearchSuggestionListProps } from \"./types\";\n\nconst rowClassName =\n  \"flex w-full flex-col gap-0.5 rounded-lg px-3 py-2.5 text-left text-sm transition-colors hover:bg-white/5 focus-visible:bg-white/5 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-400/50\";\n\nexport function SearchSuggestionList({\n  items,\n  onSelect,\n  activeId,\n  onActiveIdChange,\n  listboxId,\n  className,\n  listClassName,\n  emptyLabel,\n}: SearchSuggestionListProps) {\n  if (items.length === 0) {\n    return (\n      <div\n        data-slot=\"search-suggestion-list-empty\"\n        className={cn(\"px-1 py-6 text-center text-sm text-slate-500\", className)}\n      >\n        {emptyLabel ?? \"No matches.\"}\n      </div>\n    );\n  }\n\n  let lastGroup: string | undefined;\n  const useListbox = Boolean(listboxId);\n\n  return (\n    <nav\n      data-slot=\"search-suggestion-list\"\n      aria-label=\"Search results\"\n      className={cn(\"flex max-h-[min(50vh,360px)] flex-col gap-1 overflow-y-auto pr-1\", className)}\n    >\n      <div\n        {...(useListbox\n          ? {\n              id: listboxId,\n              role: \"listbox\" as const,\n            }\n          : {})}\n        className={cn(\"flex flex-col gap-0.5\", listClassName)}\n      >\n        {items.map((item) => {\n          const showGroup = item.group && item.group !== lastGroup;\n          if (item.group) {\n            lastGroup = item.group;\n          }\n          const isActive = activeId === item.id;\n          const optionDomId =\n            useListbox && listboxId ? searchSuggestionOptionDomId(listboxId, item.id) : undefined;\n          return (\n            <Fragment key={item.id}>\n              {showGroup ? (\n                <div\n                  role=\"presentation\"\n                  className=\"sticky top-0 z-1 bg-slate-950/95 px-2 pb-1 pt-2 text-xs font-semibold uppercase tracking-wide text-slate-500 backdrop-blur-sm\"\n                >\n                  {item.group}\n                </div>\n              ) : null}\n              <button\n                type=\"button\"\n                id={optionDomId}\n                role={useListbox ? \"option\" : undefined}\n                aria-selected={useListbox ? isActive : undefined}\n                data-active={isActive ? \"\" : undefined}\n                className={cn(rowClassName, isActive ? \"bg-white/5\" : null)}\n                onMouseEnter={() => onActiveIdChange?.(item.id)}\n                onFocus={() => onActiveIdChange?.(item.id)}\n                onClick={() => onSelect(item.id)}\n              >\n                <span className=\"font-medium text-slate-100\">{item.label}</span>\n                {item.description ? (\n                  <span className=\"truncate text-xs text-slate-500\">{item.description}</span>\n                ) : null}\n              </button>\n            </Fragment>\n          );\n        })}\n      </div>\n    </nav>\n  );\n}\n\nSearchSuggestionList.displayName = \"SearchSuggestionList\";\n\n","import type { SearchFilterable } from \"./types\";\n\nexport type FilterSearchSuggestionsOptions = {\n  /** Maximum number of matches returned. */\n  maxResults?: number;\n};\n\n/**\n * Returns items whose label, description, href, or keywords contain the query (case-insensitive).\n * Whitespace-only query matches no items.\n */\nexport function filterSearchSuggestions<T extends SearchFilterable>({\n  query,\n  items,\n  options = { maxResults: 20 },\n}: {\n  query: string;\n  items: readonly T[];\n  options?: FilterSearchSuggestionsOptions;\n}): T[] {\n  const maxResults = options.maxResults ?? 20;\n  const normalized = query.trim().toLowerCase();\n  if (!normalized) {\n    return [];\n  }\n\n  const matches: T[] = [];\n  for (const item of items) {\n    const isMatch =\n      item.label.toLowerCase().includes(normalized) ||\n      (item.description?.toLowerCase().includes(normalized)) ||\n      (item.href?.toLowerCase().includes(normalized)) ||\n      (item.keywords?.some((k) => k.toLowerCase().includes(normalized)));\n\n    if (isMatch) {\n      matches.push(item);\n      if (matches.length >= maxResults || maxResults <= 0) {\n        break;\n      }\n    }\n  }\n  return matches;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zentauri-ui/zentauri-components",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "description": "React + Tailwind UI kit with ESM/CJS builds, per-entry exports, and a zentauri-components / zentauri-ui CLI to vendor UI or hook source into your app",
   "license": "MIT",
   "files": ["dist", "src/ui", "src/lib", "src/hooks", "cli"],
@@ -45,8 +45,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "react": ">=18",
-    "react-dom": ">=18",
+    "react": ">18",
+    "react-dom": ">18",
     "class-variance-authority": "*",
     "clsx": "*",
     "tailwind-merge": "*",

package/src/ui/search/filter-search-suggestions.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+
+import { filterSearchSuggestions } from "./filter-search-suggestions";
+import type { SearchFilterable } from "./types";
+
+const sampleItems: SearchFilterable[] = [
+  { id: "1", label: "Installation", href: "/preview/installation", keywords: ["npm", "setup"] },
+  { id: "2", label: "Modal", href: "/preview/components/modal" },
+  { id: "3", label: "GitHub", href: "https://example.com/repo", keywords: ["github", "source"] },
+];
+
+describe("filterSearchSuggestions", () => {
+  it("returns empty list for whitespace-only query", () => {
+    expect(filterSearchSuggestions({ query: "   ", items: sampleItems })).toEqual([]);
+  });
+
+  it("returns empty list for empty query", () => {
+    expect(filterSearchSuggestions({ query: "", items: sampleItems })).toEqual([]);
+  });
+
+  it("matches label case-insensitively", () => {
+    expect(filterSearchSuggestions({ query: "modal", items: sampleItems })).toEqual([
+      { id: "2", label: "Modal", href: "/preview/components/modal" },
+    ]);
+  });
+
+  it("matches href substring", () => {
+    expect(filterSearchSuggestions({ query: "installation", items: sampleItems })).toEqual([
+      { id: "1", label: "Installation", href: "/preview/installation", keywords: ["npm", "setup"] },
+    ]);
+  });
+
+  it("matches keywords", () => {
+    expect(filterSearchSuggestions({ query: "github", items: sampleItems })).toEqual([
+      { id: "3", label: "GitHub", href: "https://example.com/repo", keywords: ["github", "source"] },
+    ]);
+  });
+
+  it("respects maxResults", () => {
+    const many: SearchFilterable[] = Array.from({ length: 30 }, (_, index) => ({
+      id: `x-${index}`,
+      label: `Item ${index}`,
+      href: `/x/${index}`,
+      keywords: ["alpha"],
+    }));
+    expect(filterSearchSuggestions({ query: "alpha", items: many, options: { maxResults: 5 } })).toHaveLength(5);
+  });
+});

package/src/ui/search/filter-search-suggestions.ts

@@ -0,0 +1,43 @@
+import type { SearchFilterable } from "./types";
+
+export type FilterSearchSuggestionsOptions = {
+  /** Maximum number of matches returned. */
+  maxResults?: number;
+};
+
+/**
+ * Returns items whose label, description, href, or keywords contain the query (case-insensitive).
+ * Whitespace-only query matches no items.
+ */
+export function filterSearchSuggestions<T extends SearchFilterable>({
+  query,
+  items,
+  options = { maxResults: 20 },
+}: {
+  query: string;
+  items: readonly T[];
+  options?: FilterSearchSuggestionsOptions;
+}): T[] {
+  const maxResults = options.maxResults ?? 20;
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) {
+    return [];
+  }
+
+  const matches: T[] = [];
+  for (const item of items) {
+    const isMatch =
+      item.label.toLowerCase().includes(normalized) ||
+      (item.description?.toLowerCase().includes(normalized)) ||
+      (item.href?.toLowerCase().includes(normalized)) ||
+      (item.keywords?.some((k) => k.toLowerCase().includes(normalized)));
+
+    if (isMatch) {
+      matches.push(item);
+      if (matches.length >= maxResults || maxResults <= 0) {
+        break;
+      }
+    }
+  }
+  return matches;
+}

package/src/ui/search/index.ts

@@ -0,0 +1,11 @@
+export { SearchBar } from "./search-bar";
+export { SearchSuggestionList } from "./search-suggestion-list";
+export { searchSuggestionOptionDomId } from "./search-suggestion-utils";
+export { filterSearchSuggestions } from "./filter-search-suggestions";
+export type {
+  SearchBarProps,
+  SearchSuggestionItem,
+  SearchSuggestionListProps,
+  SearchFilterable,
+} from "./types";
+export type { FilterSearchSuggestionsOptions } from "./filter-search-suggestions";

package/src/ui/search/search-bar.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+import { forwardRef, useId } from "react";
+
+import { cn } from "../../lib/utils";
+import { inputVariants } from "../inputs/variants";
+
+import type { SearchBarProps } from "./types";
+
+export const SearchBar = function SearchBar(
+  {
+    value,
+    onValueChange,
+    leadingSlot,
+    className,
+    inputClassName,
+    appearance = "default",
+    inputSize = "md",
+    ring = true,
+    id,
+    onChange,
+    disabled,
+    type,
+    comboboxListboxId,
+    comboboxActiveOptionId,
+    comboboxExpanded,
+    ref,
+    ...rest
+  }: SearchBarProps,
+) {
+  const generatedId = useId();
+  const controlId = id ?? generatedId;
+  const combobox = Boolean(comboboxListboxId);
+
+  return (
+    <div
+      data-slot="search-bar"
+      className={cn("relative flex w-full min-w-0 items-center", className)}
+    >
+      {leadingSlot ? (
+        <span
+          className="pointer-events-none absolute left-3 top-1/2 z-1 flex -translate-y-1/2 text-slate-400 [&_svg]:size-4"
+          aria-hidden
+        >
+          {leadingSlot}
+        </span>
+      ) : null}
+      <input
+        ref={ref}
+        id={controlId}
+        type={type ?? "search"}
+        autoComplete="off"
+        spellCheck={false}
+        disabled={disabled}
+        value={value}
+        data-slot="search-bar-input"
+        className={cn(
+          inputVariants({ appearance, size: inputSize, ring, as: "input" }),
+          leadingSlot ? "pl-10" : null,
+          inputClassName,
+        )}
+        onChange={(event) => {
+          onChange?.(event);
+          onValueChange?.(event.target.value);
+        }}
+        {...(combobox
+          ? {
+              role: "combobox" as const,
+              "aria-autocomplete": "list" as const,
+              "aria-controls": comboboxListboxId,
+              "aria-expanded": comboboxExpanded ?? false,
+              ...(comboboxActiveOptionId
+                ? { "aria-activedescendant": comboboxActiveOptionId }
+                : {}),
+            }
+          : {})}
+        {...rest}
+      />
+    </div>
+  );
+}
+
+SearchBar.displayName = "SearchBar";

package/src/ui/search/search-suggestion-list.tsx

@@ -0,0 +1,95 @@
+"use client";
+
+import { Fragment } from "react";
+
+import { cn } from "../../lib/utils";
+import { searchSuggestionOptionDomId } from "./search-suggestion-utils";
+
+import type { SearchSuggestionListProps } from "./types";
+
+const rowClassName =
+  "flex w-full flex-col gap-0.5 rounded-lg px-3 py-2.5 text-left text-sm transition-colors hover:bg-white/5 focus-visible:bg-white/5 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-400/50";
+
+export function SearchSuggestionList({
+  items,
+  onSelect,
+  activeId,
+  onActiveIdChange,
+  listboxId,
+  className,
+  listClassName,
+  emptyLabel,
+}: SearchSuggestionListProps) {
+  if (items.length === 0) {
+    return (
+      <div
+        data-slot="search-suggestion-list-empty"
+        className={cn("px-1 py-6 text-center text-sm text-slate-500", className)}
+      >
+        {emptyLabel ?? "No matches."}
+      </div>
+    );
+  }
+
+  let lastGroup: string | undefined;
+  const useListbox = Boolean(listboxId);
+
+  return (
+    <nav
+      data-slot="search-suggestion-list"
+      aria-label="Search results"
+      className={cn("flex max-h-[min(50vh,360px)] flex-col gap-1 overflow-y-auto pr-1", className)}
+    >
+      <div
+        {...(useListbox
+          ? {
+              id: listboxId,
+              role: "listbox" as const,
+            }
+          : {})}
+        className={cn("flex flex-col gap-0.5", listClassName)}
+      >
+        {items.map((item) => {
+          const showGroup = item.group && item.group !== lastGroup;
+          if (item.group) {
+            lastGroup = item.group;
+          }
+          const isActive = activeId === item.id;
+          const optionDomId =
+            useListbox && listboxId ? searchSuggestionOptionDomId(listboxId, item.id) : undefined;
+          return (
+            <Fragment key={item.id}>
+              {showGroup ? (
+                <div
+                  role="presentation"
+                  className="sticky top-0 z-1 bg-slate-950/95 px-2 pb-1 pt-2 text-xs font-semibold uppercase tracking-wide text-slate-500 backdrop-blur-sm"
+                >
+                  {item.group}
+                </div>
+              ) : null}
+              <button
+                type="button"
+                id={optionDomId}
+                role={useListbox ? "option" : undefined}
+                aria-selected={useListbox ? isActive : undefined}
+                data-active={isActive ? "" : undefined}
+                className={cn(rowClassName, isActive ? "bg-white/5" : null)}
+                onMouseEnter={() => onActiveIdChange?.(item.id)}
+                onFocus={() => onActiveIdChange?.(item.id)}
+                onClick={() => onSelect(item.id)}
+              >
+                <span className="font-medium text-slate-100">{item.label}</span>
+                {item.description ? (
+                  <span className="truncate text-xs text-slate-500">{item.description}</span>
+                ) : null}
+              </button>
+            </Fragment>
+          );
+        })}
+      </div>
+    </nav>
+  );
+}
+
+SearchSuggestionList.displayName = "SearchSuggestionList";
+

package/src/ui/search/search-suggestion-utils.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from "vitest";
+
+import { searchSuggestionOptionDomId } from "./search-suggestion-utils";
+
+describe("searchSuggestionOptionDomId", () => {
+  it("prefixes listbox id and sanitizes item id", () => {
+    expect(searchSuggestionOptionDomId(":lb:", "/a/b")).toBe(":lb:_opt__a_b");
+  });
+});

package/src/ui/search/search-suggestion-utils.ts

@@ -0,0 +1,8 @@
+/**
+ * Builds a stable DOM id for a listbox option so `aria-activedescendant` on the combobox
+ * input can reference it. Safe for href-like `itemId` strings.
+ */
+export function searchSuggestionOptionDomId(listboxId: string, itemId: string): string {
+  const safe = itemId.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return `${listboxId}_opt_${safe}`;
+}

package/src/ui/search/types.ts

@@ -0,0 +1,52 @@
+import type { InputHTMLAttributes, ReactNode, Ref } from "react";
+
+import type { VariantProps } from "class-variance-authority";
+
+import type { inputVariants } from "../inputs/variants";
+
+export type SearchBarProps = Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  "size" | "children" | "role"
+> & {
+  value: string;
+  onValueChange?: (value: string) => void;
+  leadingSlot?: ReactNode;
+  inputClassName?: string;
+  appearance?: VariantProps<typeof inputVariants>["appearance"];
+  inputSize?: VariantProps<typeof inputVariants>["size"];
+  ring?: VariantProps<typeof inputVariants>["ring"];
+  /** When set, the input exposes combobox semantics wired to a `role="listbox"` with this id. */
+  comboboxListboxId?: string;
+  /** Element id of the active option (from `searchSuggestionOptionDomId`) for `aria-activedescendant`. */
+  comboboxActiveOptionId?: string;
+  /** Whether the suggestion list is visibly expanded (controls `aria-expanded`). */
+  comboboxExpanded?: boolean;
+  ref?: Ref<HTMLInputElement>;
+};
+
+export type SearchSuggestionItem = {
+  id: string;
+  label: string;
+  description?: string;
+  group?: string;
+};
+
+export type SearchSuggestionListProps = {
+  items: readonly SearchSuggestionItem[];
+  onSelect: (id: string) => void;
+  activeId?: string;
+  onActiveIdChange?: (id: string | undefined) => void;
+  /** Pass the same id as `comboboxListboxId` on `SearchBar` for ARIA wiring. */
+  listboxId?: string;
+  className?: string;
+  listClassName?: string;
+  emptyLabel?: ReactNode;
+};
+
+export type SearchFilterable = {
+  id: string;
+  label: string;
+  description?: string;
+  keywords?: readonly string[];
+  href?: string;
+};