@dbx-tools/ui-search 0.6.9

package/README.md

@@ -0,0 +1,66 @@
+# @dbx-tools/ui-search
+
+React search box and results for Databricks AI Search.
+
+Import this package when an AppKit UI wants a drop-in, search-as-you-type box
+over the [`@dbx-tools/search`](../../node/search) plugin. The components
+read the plugin's boot config (indexes, default index, page size, route path)
+through AppKit's `usePluginClientConfig`, so search is one component and zero
+props.
+
+**Key features:**
+
+- `SearchBox` - a debounced, cancellable search-as-you-type input with a results
+  dropdown, styled with AppKit tokens. Meilisearch-style instant search.
+- `SearchResults` - a presentational hit list for a full-page results layout.
+- `useSearch` - the hook the components share: `{ query, setQuery, hits,
+loading, error, config, submit, clear }`, debounced and abortable, targeting
+  the single-index or universal (federated) route.
+- Universal search with one flag (`universal`) to search every configured index.
+- `renderHit` overrides on both components for full control of a row; a sensible
+  default shows a title, id, and score.
+
+## Quick Start
+
+```tsx
+import { SearchBox } from "@dbx-tools/ui-search/react";
+import "@dbx-tools/ui-search/styles.css";
+
+export function DocsSearch() {
+  return <SearchBox placeholder="Search docs…" onSelect={(hit) => open(hit.id)} />;
+}
+```
+
+Universal search across every index the plugin knows about:
+
+```tsx
+<SearchBox universal showIndex placeholder="Search everything…" />
+```
+
+## Use The Hook
+
+```tsx
+import { useSearch, SearchResults } from "@dbx-tools/ui-search/react";
+
+function Results() {
+  const { query, setQuery, hits, loading } = useSearch({ limit: 20 });
+  return (
+    <>
+      <input value={query} onChange={(e) => setQuery(e.target.value)} />
+      {loading ? "…" : <SearchResults hits={hits} />}
+    </>
+  );
+}
+```
+
+## Subpaths
+
+- `@dbx-tools/ui-search/react` - `SearchBox`, `SearchResults`, `useSearch`,
+  and the re-exported `SearchHit` / `SearchResult` / `SearchMode` /
+  `SearchClientConfig` types.
+- `@dbx-tools/ui-search/styles.css` - AppKit-token styling for the box and
+  results; import once after Tailwind and your AppKit-UI theme.
+
+Runtime search, routes, and the plugin live in
+[`@dbx-tools/search`](../../node/search); the wire contract lives in
+[`@dbx-tools/shared-search`](../../shared/search).

package/index.ts

@@ -0,0 +1,13 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as reactSearchBox from "./src/react/search-box.tsx";
+export * as reactSearchResults from "./src/react/search-results.tsx";
+export * as reactUseSearch from "./src/react/use-search.ts";
+export { SearchBox } from "./src/react/search-box.tsx";
+export type { SearchBoxProps } from "./src/react/search-box.tsx";
+export { SearchResults } from "./src/react/search-results.tsx";
+export type { SearchResultsProps } from "./src/react/search-results.tsx";
+export { useSearch } from "./src/react/use-search.ts";
+export type { UseSearchOptions, UseSearchState } from "./src/react/use-search.ts";

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@dbx-tools/ui-search",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "packages/ui/search"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "lucide-react": "^0.554.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "@dbx-tools/shared-core": "0.6.9",
+    "@dbx-tools/shared-search": "0.6.9",
+    "@dbx-tools/ui-appkit": "0.6.9"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.6.9",
+  "type": "module",
+  "exports": {
+    "./react": "./src/react/index.ts",
+    "./styles.css": "./src/styles.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "dbxToolsConfig": {
+    "tags": [
+      "ui"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/react/index.ts

@@ -0,0 +1,16 @@
+// React surface for `@dbx-tools/ui-search`: a drop-in `SearchBox`
+// (search-as-you-type over Databricks AI Search), a `SearchResults` list for a
+// full-page layout, and the `useSearch` hook they share. All three talk to the
+// `@dbx-tools/search` plugin's routes and read its boot config through
+// AppKit's `usePluginClientConfig`, so search is one component and zero props.
+// Styled with AppKit tokens (import `@dbx-tools/ui-search/styles.css`).
+
+export type {
+  SearchHit,
+  SearchResult,
+  SearchMode,
+  SearchClientConfig,
+} from "@dbx-tools/shared-search";
+export { SearchBox, type SearchBoxProps } from "./search-box.tsx";
+export { SearchResults, type SearchResultsProps } from "./search-results.tsx";
+export { useSearch, type UseSearchOptions, type UseSearchState } from "./use-search.ts";

package/src/react/search-box.tsx

@@ -0,0 +1,146 @@
+// `SearchBox` — a drop-in, Meilisearch-style search-as-you-type input for
+// Databricks AI Search. It wires an AppKit `Input` to the {@link useSearch}
+// hook and renders the hits in a dropdown as the user types, so adding search
+// to an app is one component and zero configuration: the plugin's client config
+// supplies the index, page size, and route.
+//
+// It is presentational and unopinionated about what a hit looks like: pass a
+// `renderHit` to control each row, or rely on the default which shows the first
+// string-ish field as a title and the primary-key `id` as a subtitle. Styled
+// with AppKit tokens (see `../styles.css`).
+
+import type { SearchHit } from "@dbx-tools/shared-search";
+import { Badge, Button, Input, ScrollArea, Spinner, cn } from "@dbx-tools/ui-appkit/react";
+import { SearchIcon, XIcon } from "lucide-react";
+import { useCallback, useState, type ReactNode } from "react";
+import { useSearch, type UseSearchOptions } from "./use-search.ts";
+
+/** Props for {@link SearchBox}. */
+export interface SearchBoxProps extends UseSearchOptions {
+  /** Placeholder text for the input. */
+  placeholder?: string;
+  /** Called when the user picks a hit (click or Enter on a focused row). */
+  onSelect?: (hit: SearchHit) => void;
+  /** Render one hit row. Defaults to a title + id + score badge. */
+  renderHit?: (hit: SearchHit) => ReactNode;
+  /** Show the source index name on each hit (useful for universal search). */
+  showIndex?: boolean;
+  /** Extra class names for the outer container. */
+  className?: string;
+}
+
+/** Pick the most title-like string field from a hit for the default row. */
+function hitTitle(hit: SearchHit): string {
+  for (const key of ["title", "name", "text", "content", "body"]) {
+    const value = hit.fields[key];
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  const firstString = Object.values(hit.fields).find(
+    (value) => typeof value === "string" && value.trim(),
+  );
+  return typeof firstString === "string" ? firstString : hit.id;
+}
+
+/**
+ * A search-as-you-type box over AI Search. Renders an input and a results
+ * dropdown, debouncing keystrokes and cancelling stale requests through
+ * {@link useSearch}.
+ *
+ * @example
+ * ```tsx
+ * import { SearchBox } from "@dbx-tools/ui-search/react";
+ * import "@dbx-tools/ui-search/styles.css";
+ *
+ * <SearchBox placeholder="Search docs…" onSelect={(hit) => open(hit.id)} />
+ * ```
+ */
+export function SearchBox({
+  placeholder = "Search…",
+  onSelect,
+  renderHit,
+  showIndex,
+  className,
+  ...searchOptions
+}: SearchBoxProps): ReactNode {
+  const { query, setQuery, hits, loading, error, clear, submit } = useSearch(searchOptions);
+  const [open, setOpen] = useState(false);
+
+  const handleSelect = useCallback(
+    (hit: SearchHit) => {
+      onSelect?.(hit);
+      setOpen(false);
+    },
+    [onSelect],
+  );
+
+  return (
+    <div className={cn("dbx-search-box", className)}>
+      <div className="dbx-search-box__field">
+        <SearchIcon className="dbx-search-box__icon" aria-hidden />
+        <Input
+          value={query}
+          placeholder={placeholder}
+          aria-label={placeholder}
+          onChange={(event) => {
+            setQuery(event.target.value);
+            setOpen(true);
+          }}
+          onFocus={() => setOpen(true)}
+          onKeyDown={(event) => {
+            if (event.key === "Enter") submit();
+            if (event.key === "Escape") setOpen(false);
+          }}
+        />
+        {loading ? <Spinner className="dbx-search-box__spinner" /> : null}
+        {query ? (
+          <Button
+            variant="ghost"
+            size="icon"
+            aria-label="Clear search"
+            onClick={() => {
+              clear();
+              setOpen(false);
+            }}
+          >
+            <XIcon />
+          </Button>
+        ) : null}
+      </div>
+
+      {open && (query.trim() || error) ? (
+        <div className="dbx-search-box__panel" role="listbox">
+          {error ? <div className="dbx-search-box__error">{error}</div> : null}
+          {!error && hits.length === 0 && !loading ? (
+            <div className="dbx-search-box__empty">No results</div>
+          ) : null}
+          <ScrollArea className="dbx-search-box__results">
+            {hits.map((hit) => (
+              <button
+                key={`${hit.index ?? ""}:${hit.id}`}
+                type="button"
+                role="option"
+                aria-selected={false}
+                className="dbx-search-box__hit"
+                onClick={() => handleSelect(hit)}
+              >
+                {renderHit ? (
+                  renderHit(hit)
+                ) : (
+                  <div className="dbx-search-box__hit-default">
+                    <span className="dbx-search-box__hit-title">{hitTitle(hit)}</span>
+                    <span className="dbx-search-box__hit-meta">
+                      {showIndex && hit.index ? (
+                        <Badge variant="secondary">{hit.index}</Badge>
+                      ) : null}
+                      <span className="dbx-search-box__hit-id">{hit.id}</span>
+                    </span>
+                  </div>
+                )}
+              </button>
+            ))}
+          </ScrollArea>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/react/search-results.tsx

@@ -0,0 +1,75 @@
+// `SearchResults` — a presentational list of AI Search hits for a full-page
+// results layout (as opposed to the `SearchBox` dropdown). Give it `hits` from
+// `useSearch` (or any `SearchResult`) and it renders a scored, index-tagged
+// list; pass `renderHit` to control a row. Styled with AppKit tokens.
+
+import type { SearchHit } from "@dbx-tools/shared-search";
+import { Badge, cn } from "@dbx-tools/ui-appkit/react";
+import type { ReactNode } from "react";
+
+/** Props for {@link SearchResults}. */
+export interface SearchResultsProps {
+  /** The hits to render, most relevant first. */
+  hits: SearchHit[];
+  /** Called when a hit is clicked. */
+  onSelect?: (hit: SearchHit) => void;
+  /** Render one hit row. Defaults to a title, fields, and a score badge. */
+  renderHit?: (hit: SearchHit) => ReactNode;
+  /** Show each hit's source index (useful for universal search). */
+  showIndex?: boolean;
+  /** Message shown when there are no hits. */
+  emptyMessage?: ReactNode;
+  /** Extra class names for the container. */
+  className?: string;
+}
+
+function hitTitle(hit: SearchHit): string {
+  for (const key of ["title", "name", "text", "content", "body"]) {
+    const value = hit.fields[key];
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  return hit.id;
+}
+
+/** A full-page list of search hits. */
+export function SearchResults({
+  hits,
+  onSelect,
+  renderHit,
+  showIndex,
+  emptyMessage = "No results",
+  className,
+}: SearchResultsProps): ReactNode {
+  if (hits.length === 0) {
+    return <div className={cn("dbx-search-results__empty", className)}>{emptyMessage}</div>;
+  }
+  return (
+    <ul className={cn("dbx-search-results", className)}>
+      {hits.map((hit) => (
+        <li key={`${hit.index ?? ""}:${hit.id}`} className="dbx-search-results__item">
+          <button
+            type="button"
+            className="dbx-search-results__button"
+            onClick={() => onSelect?.(hit)}
+          >
+            {renderHit ? (
+              renderHit(hit)
+            ) : (
+              <>
+                <div className="dbx-search-results__header">
+                  <span className="dbx-search-results__title">{hitTitle(hit)}</span>
+                  <Badge variant="outline">{hit.score.toFixed(3)}</Badge>
+                </div>
+                {showIndex && hit.index ? (
+                  <Badge variant="secondary" className="dbx-search-results__index">
+                    {hit.index}
+                  </Badge>
+                ) : null}
+              </>
+            )}
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/react/use-search.ts

@@ -0,0 +1,161 @@
+// `useSearch` — a small React hook that turns the AI Search plugin's HTTP
+// routes into a debounced, cancellable search-as-you-type state machine. It
+// reads the plugin's boot config (indexes, default index, page size, base path)
+// via AppKit's `usePluginClientConfig`, so a search box needs no props to know
+// where to POST. Point it at `@dbx-tools/search`'s `POST /api/search`
+// (single index) or `POST /api/search/universal` (federated) route.
+
+import type {
+  SearchClientConfig,
+  SearchHit,
+  SearchMode,
+  SearchResult,
+} from "@dbx-tools/shared-search";
+import { usePluginClientConfig } from "@dbx-tools/ui-appkit/react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+/** Options for {@link useSearch}. */
+export interface UseSearchOptions {
+  /** Which index to search (name or alias). Defaults to the plugin's default index. */
+  index?: string;
+  /** Search every configured index and merge results (universal search). */
+  universal?: boolean;
+  /** Match mode. Defaults to the plugin's configured mode. */
+  mode?: SearchMode;
+  /** Max hits to request. Defaults to the plugin's configured page size. */
+  limit?: number;
+  /** Debounce in ms before a keystroke triggers a request. Defaults to 200. */
+  debounceMs?: number;
+  /** Minimum query length before searching. Defaults to 1. */
+  minLength?: number;
+  /** The plugin name to read config from / route under. Defaults to "search". */
+  pluginName?: string;
+}
+
+/** The state {@link useSearch} returns. */
+export interface UseSearchState {
+  /** The current query text. */
+  query: string;
+  /** Set the query (triggers a debounced search). */
+  setQuery: (query: string) => void;
+  /** The latest hits, most relevant first. */
+  hits: SearchHit[];
+  /** True while a request is in flight. */
+  loading: boolean;
+  /** The last error, if any. */
+  error: string | null;
+  /** The resolved plugin config (indexes, default, page size). */
+  config: SearchClientConfig | undefined;
+  /** Run the search immediately (bypassing the debounce). */
+  submit: () => void;
+  /** Clear the query and hits. */
+  clear: () => void;
+}
+
+const DEFAULT_BASE_PATH = "/api/search";
+
+/**
+ * Search-as-you-type against the AI Search plugin. Debounces input, cancels the
+ * previous request when a new one starts, and exposes `{ query, setQuery, hits,
+ * loading, error }` for a search box to render. Reads the plugin's client config
+ * for the base path, default index, and page size.
+ */
+export function useSearch(options: UseSearchOptions = {}): UseSearchState {
+  const pluginName = options.pluginName ?? "search";
+  const config = usePluginClientConfig<SearchClientConfig>(pluginName);
+  const basePath = config?.basePath ?? DEFAULT_BASE_PATH;
+  const debounceMs = options.debounceMs ?? 200;
+  const minLength = options.minLength ?? 1;
+
+  const [query, setQueryState] = useState("");
+  const [hits, setHits] = useState<SearchHit[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const abortRef = useRef<AbortController | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const run = useCallback(
+    async (text: string) => {
+      abortRef.current?.abort();
+      if (text.trim().length < minLength) {
+        setHits([]);
+        setLoading(false);
+        return;
+      }
+      const controller = new AbortController();
+      abortRef.current = controller;
+      setLoading(true);
+      setError(null);
+      try {
+        const path = options.universal ? `${basePath}/universal` : basePath;
+        const body = options.universal
+          ? {
+              query: text,
+              ...(options.limit ? { limit: options.limit } : {}),
+              ...(options.mode ? { mode: options.mode } : {}),
+            }
+          : {
+              query: text,
+              ...(options.index ? { index: options.index } : {}),
+              ...(options.limit ? { limit: options.limit } : {}),
+              ...(options.mode ? { mode: options.mode } : {}),
+            };
+        const response = await fetch(path, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(body),
+          signal: controller.signal,
+        });
+        if (!response.ok) {
+          throw new Error(`search failed (${response.status})`);
+        }
+        const result = (await response.json()) as SearchResult;
+        setHits(result.hits ?? []);
+      } catch (err) {
+        if ((err as Error).name === "AbortError") return;
+        setError((err as Error).message);
+        setHits([]);
+      } finally {
+        if (abortRef.current === controller) setLoading(false);
+      }
+    },
+    [basePath, minLength, options.index, options.limit, options.mode, options.universal],
+  );
+
+  const setQuery = useCallback(
+    (text: string) => {
+      setQueryState(text);
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => void run(text), debounceMs);
+    },
+    [debounceMs, run],
+  );
+
+  const submit = useCallback(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    void run(query);
+  }, [query, run]);
+
+  const clear = useCallback(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    abortRef.current?.abort();
+    setQueryState("");
+    setHits([]);
+    setError(null);
+    setLoading(false);
+  }, []);
+
+  useEffect(
+    () => () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      abortRef.current?.abort();
+    },
+    [],
+  );
+
+  return useMemo(
+    () => ({ query, setQuery, hits, loading, error, config, submit, clear }),
+    [query, setQuery, hits, loading, error, config, submit, clear],
+  );
+}

package/src/styles.css

@@ -0,0 +1,156 @@
+/*
+ * @dbx-tools/ui-search stylesheet.
+ *
+ * Import once from the host app's Tailwind entry, after Tailwind and
+ * your AppKit-UI theme:
+ *
+ *   @import "tailwindcss";
+ *   @import "@databricks/appkit-ui/styles.css";
+ *   @import "@dbx-tools/ui-search/styles.css";
+ *
+ * Defines NO design tokens - the search box / results style exclusively with
+ * AppKit semantic tokens and inherit the host app's theme. Registers this
+ * package's React components with Tailwind via `@source`.
+ */
+
+@import "@dbx-tools/ui-appkit/styles.css";
+
+@source "./react";
+
+.dbx-search-box {
+  position: relative;
+  width: 100%;
+}
+
+.dbx-search-box__field {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.dbx-search-box__icon {
+  position: absolute;
+  left: 0.625rem;
+  width: 1rem;
+  height: 1rem;
+  color: var(--muted-foreground, currentColor);
+  pointer-events: none;
+}
+
+.dbx-search-box__field :where(input) {
+  padding-left: 2rem;
+}
+
+.dbx-search-box__spinner {
+  position: absolute;
+  right: 2.25rem;
+}
+
+.dbx-search-box__panel {
+  position: absolute;
+  z-index: 50;
+  margin-top: 0.25rem;
+  width: 100%;
+  overflow: hidden;
+  border-radius: var(--radius, 0.5rem);
+  border: 1px solid var(--border, currentColor);
+  background: var(--popover, var(--background));
+  color: var(--popover-foreground, var(--foreground));
+  box-shadow: 0 10px 30px -12px rgb(0 0 0 / 0.35);
+}
+
+.dbx-search-box__results {
+  max-height: 20rem;
+}
+
+.dbx-search-box__hit {
+  display: block;
+  width: 100%;
+  text-align: left;
+  padding: 0.5rem 0.75rem;
+  cursor: pointer;
+  background: transparent;
+  border: 0;
+  color: inherit;
+}
+
+.dbx-search-box__hit:hover,
+.dbx-search-box__hit:focus-visible {
+  background: var(--accent, rgb(0 0 0 / 0.05));
+  outline: none;
+}
+
+.dbx-search-box__hit-default {
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+}
+
+.dbx-search-box__hit-title {
+  font-weight: 500;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.dbx-search-box__hit-meta {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.75rem;
+  color: var(--muted-foreground, currentColor);
+}
+
+.dbx-search-box__empty,
+.dbx-search-box__error {
+  padding: 0.75rem;
+  font-size: 0.875rem;
+  color: var(--muted-foreground, currentColor);
+}
+
+.dbx-search-box__error {
+  color: var(--destructive, currentColor);
+}
+
+.dbx-search-results {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.dbx-search-results__button {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  width: 100%;
+  text-align: left;
+  padding: 0.75rem 1rem;
+  border-radius: var(--radius, 0.5rem);
+  border: 1px solid var(--border, currentColor);
+  background: var(--card, transparent);
+  color: inherit;
+  cursor: pointer;
+}
+
+.dbx-search-results__button:hover {
+  background: var(--accent, rgb(0 0 0 / 0.05));
+}
+
+.dbx-search-results__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+}
+
+.dbx-search-results__title {
+  font-weight: 500;
+}
+
+.dbx-search-results__empty {
+  padding: 1rem;
+  color: var(--muted-foreground, currentColor);
+}