@dbx-tools/ui 0.0.0-stage → 0.9.61

package/src/search/react/use-search.ts

@@ -0,0 +1,188 @@
+// `useSearch` adapts AppKit's native `useAiSearchQuery` to a debounced
+// search-as-you-type state machine. Single-index queries use AppKit's native
+// route and client config; universal queries use the dbx-tools extension route.
+
+import { useAiSearchQuery, type AiSearchRequest } from "@databricks/appkit-ui/react/beta";
+import {
+  searchSchemas,
+  type SearchClientConfig,
+  type SearchHit,
+  type SearchMode,
+  type SearchResult,
+} from "@dbx-tools/shared-search";
+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 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 UNIVERSAL_SEARCH_PATH = "/api/search/universal";
+
+/** Validate one universal-search response with the owning shared schema. */
+export function parseUniversalSearchResult(value: unknown): SearchResult {
+  return searchSchemas.searchResultSchema.parse(value);
+}
+
+function toHits(
+  results: Array<{ score: number; data: Record<string, unknown> }>,
+  index: string | null,
+): SearchHit[] {
+  return results.map((result, resultIndex) => ({
+    id: String(result.data.id ?? Object.values(result.data)[0] ?? resultIndex),
+    score: result.score,
+    fields: result.data,
+    ...(index ? { index } : {}),
+  }));
+}
+
+/**
+ * Search-as-you-type against AppKit AI Search. Debounces input, cancels stale
+ * native queries, and exposes `{ query, setQuery, hits, loading, error }` for a
+ * search box to render.
+ */
+export function useSearch(options: UseSearchOptions = {}): UseSearchState {
+  const native = useAiSearchQuery({ ...(options.index ? { alias: options.index } : {}) });
+  const debounceMs = options.debounceMs ?? 200;
+  const minLength = options.minLength ?? 1;
+
+  const [query, setQueryState] = useState("");
+  const [hits, setHits] = useState<SearchHit[]>([]);
+  const [universalLoading, setUniversalLoading] = useState(false);
+  const [universalError, setUniversalError] = 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([]);
+        setUniversalLoading(false);
+        return;
+      }
+      if (!options.universal) {
+        const resolvedQueryType = searchSchemas.toAiSearchQueryType(options.mode);
+        const request: AiSearchRequest = {
+          queryText: text,
+          ...(options.limit ? { numResults: options.limit } : {}),
+          ...(resolvedQueryType ? { queryType: resolvedQueryType } : {}),
+        };
+        const result = await native.search(request);
+        setHits(result ? toHits(result.results, native.alias) : []);
+        return;
+      }
+      const controller = new AbortController();
+      abortRef.current = controller;
+      setUniversalLoading(true);
+      setUniversalError(null);
+      try {
+        const response = await fetch(UNIVERSAL_SEARCH_PATH, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            query: text,
+            ...(options.limit ? { limit: options.limit } : {}),
+            ...(options.mode ? { mode: options.mode } : {}),
+          }),
+          signal: controller.signal,
+        });
+        if (!response.ok) {
+          throw new Error(`search failed (${response.status})`);
+        }
+        const result = parseUniversalSearchResult(await response.json());
+        setHits(result.hits);
+      } catch (err) {
+        if ((err as Error).name === "AbortError") return;
+        setUniversalError((err as Error).message);
+        setHits([]);
+      } finally {
+        if (abortRef.current === controller) setUniversalLoading(false);
+      }
+    },
+    [minLength, native.alias, native.search, 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([]);
+    setUniversalError(null);
+    setUniversalLoading(false);
+  }, []);
+
+  useEffect(
+    () => () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      abortRef.current?.abort();
+    },
+    [],
+  );
+
+  const config = useMemo<SearchClientConfig>(
+    () => ({
+      indexes: native.indexes.map((index) => ({
+        name: index.alias,
+        alias: index.alias,
+        isDefault: index.alias === native.alias,
+      })),
+      ...(native.alias ? { defaultIndex: native.alias } : {}),
+      pageSize: options.limit ?? 20,
+      basePath: "/api/ai-search",
+    }),
+    [native.alias, native.indexes, options.limit],
+  );
+  const loading = options.universal ? universalLoading : native.loading;
+  const error = options.universal ? universalError : native.error;
+  return useMemo(
+    () => ({ query, setQuery, hits, loading, error, config, submit, clear }),
+    [query, setQuery, hits, loading, error, config, submit, clear],
+  );
+}

package/src/search/styles.css

@@ -0,0 +1,145 @@
+/*
+ * @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/styles.css";
+
+@source "./react";
+
+.dbx-search-box {
+  position: relative;
+  width: 100%;
+}
+
+.dbx-search-box__field {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+
+.dbx-search-box__field [data-slot="command-input-wrapper"] {
+  width: 100%;
+  border: 1px solid var(--border, currentColor);
+  border-radius: var(--radius, 0.5rem);
+}
+
+.dbx-search-box__field [data-slot="command-input"] {
+  padding-right: 4.5rem;
+}
+
+.dbx-search-box__spinner {
+  position: absolute;
+  right: 2.25rem;
+}
+
+.dbx-search-box__clear {
+  position: absolute;
+  right: 0;
+}
+
+.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 {
+  padding: 0.5rem 0.75rem;
+}
+
+.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);
+}

package/src/styles.css

@@ -0,0 +1,26 @@
+/*
+ * @dbx-tools/ui shared stylesheet.
+ *
+ * Feature UI packages (`ui-email`, `ui-mastra`, ...) import
+ * this once and add their own `@source` for local class strings.
+ *
+ * Provides:
+ *   1. Streamdown's base stylesheet (markdown / code-block layout).
+ *   2. The shiki token-paint shim used by Streamdown renderers.
+ */
+
+@import "tailwindcss";
+@import "streamdown/styles.css";
+/*
+ * Brand -> AppKit token bridge. Scoped to `:root[data-brand]`, so it is inert
+ * until a host applies a brand (see `@dbx-tools/ui/branding` `applyBrandContext`
+ * / `BrandProvider applyToDocument`). Imported here so it travels with every
+ * feature UI package that depends on this shared base.
+ */
+@import "@dbx-tools/ui/branding/brand-bridge.css";
+
+@source "./react";
+
+[data-streamdown="code-block-body"] code span {
+  color: var(--sdm-c, inherit);
+}