@dbx-tools/ui 0.0.0-stage → 0.9.61

package/src/email/react/index.ts

@@ -0,0 +1,17 @@
+// React surface for `@dbx-tools/ui/email`: a read-only Approve / Deny card for
+// the `send_email` tool's approval flow, the field preview it wraps, a standard
+// editable compose view for use outside a chat bubble. The email components
+// share `./fields` and `./email-body`, so a drafted message renders identically
+// across them. Styled with AppKit tokens.
+
+export type { EmailAttachment, EmailMessage } from "@dbx-tools/shared-email";
+export {
+  EmailApprovalCard,
+  EmailPreview,
+  type EmailApprovalCardProps,
+  type EmailPreviewProps,
+} from "./email-approval-card.tsx";
+export { EmailBody, type EmailBodyProps } from "./email-body.tsx";
+export { EmailComposeView, type EmailComposeProps } from "./email-compose.tsx";
+export { attachmentNames, joinAddresses, parseAddresses } from "./fields.ts";
+export type { EmailDraft } from "./fields.ts";

package/src/email/styles.css

@@ -0,0 +1,20 @@
+/*
+ * @dbx-tools/ui/email 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/email/styles.css";
+ *
+ * Defines NO design tokens - the email preview styles exclusively with
+ * AppKit semantic tokens and inherits the host app's theme.
+ *
+ * Pulls shared Streamdown / shiki styling from `@dbx-tools/ui` and
+ * registers this package's React components with Tailwind via `@source`.
+ */
+
+@import "@dbx-tools/ui/styles.css";
+
+@source "./react";

package/src/react/appkit-ui.ts

@@ -0,0 +1,9 @@
+// Re-export of AppKit's React UI kit so the `@dbx-tools/*` UI packages import
+// their primitives (Button, Input, cn, etc.) through one stable specifier -
+// `@dbx-tools/ui/react` - and resolve AppKit + React from this package's
+// dependencies rather than each consumer's.
+//
+// This lives in a NAMED module (not the `index.ts` barrel) so package discovery
+// - which ignores barrels + `.css` - still sees `ui-appkit` as a real package.
+
+export * from "@databricks/appkit-ui/react";

package/src/react/brand-picker.tsx

@@ -0,0 +1,285 @@
+import {
+  Button,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Input,
+  Label,
+  Separator,
+  cn,
+} from "@databricks/appkit-ui/react";
+import { brandUtils, object } from "@dbx-tools/shared-core";
+import { useEffect, useId, useMemo, useState } from "react";
+
+import { useBrand } from "../branding/react/index.ts";
+
+const COLOR_FIELDS = [
+  ["primary", "Primary"],
+  ["primaryHover", "Primary hover"],
+  ["accent", "Accent"],
+  ["foreground", "Foreground"],
+  ["background", "Background"],
+  ["surface", "Surface"],
+  ["muted", "Muted"],
+  ["border", "Border"],
+] as const;
+
+type ColorField = (typeof COLOR_FIELDS)[number][0];
+
+/** One complete brand option shown above the editable fields. */
+export interface BrandPreset {
+  id: string;
+  label: string;
+  description?: string;
+  context: brandUtils.BrandContextInput;
+}
+
+/** Props for {@link BrandPicker}. */
+export interface BrandPickerProps {
+  /** Current brand. Defaults to the nearest `BrandProvider` context. */
+  value?: brandUtils.BrandContextInput;
+  /** Receives each valid edited or selected brand context. */
+  onChange: (value: brandUtils.BrandContext) => void;
+  /** Optional complete brand choices rendered as quick-select buttons. */
+  presets?: readonly BrandPreset[];
+  /** Value restored by Reset. Defaults to the dbx-tools brand. */
+  resetValue?: brandUtils.BrandContextInput;
+  /** Show editable icon, logo, and favicon references. */
+  showAssets?: boolean;
+  className?: string;
+}
+
+const validColor = (value: string, fallback: string): string =>
+  /^#(?:[\da-f]{3}|[\da-f]{6}|[\da-f]{8})$/i.test(value) ? value : fallback;
+
+/**
+ * Edit a portable `BrandContext` with AppKit-native controls.
+ *
+ * The picker keeps incomplete text locally while emitting only schema-valid
+ * contexts, so controlled hosts can apply changes directly to a
+ * `BrandProvider` without guarding every keystroke.
+ */
+export function BrandPicker({
+  value,
+  onChange,
+  presets = [],
+  resetValue = brandUtils.defaultBrandContext,
+  showAssets = true,
+  className,
+}: BrandPickerProps) {
+  const { context: inherited } = useBrand();
+  const current = useMemo(
+    () => brandUtils.parseBrandContext(value ?? inherited),
+    [inherited, value],
+  );
+  const reset = useMemo(() => brandUtils.parseBrandContext(resetValue), [resetValue]);
+  const resolvedPresets = useMemo(
+    () =>
+      presets.map((preset) => ({
+        ...preset,
+        context: brandUtils.parseBrandContext(preset.context),
+      })),
+    [presets],
+  );
+  const [draft, setDraft] = useState(current);
+  const id = useId();
+
+  useEffect(() => setDraft(current), [current]);
+
+  const update = (next: brandUtils.BrandContext) => {
+    setDraft(next);
+    const parsed = brandUtils.BrandContextSchema.safeParse(next);
+    if (parsed.success) onChange(parsed.data);
+  };
+
+  const updateIdentity = (field: "name" | "shortName" | "tagline", next: string) =>
+    update({ ...draft, [field]: next });
+
+  const updateColor = (field: ColorField, next: string) =>
+    update({ ...draft, colors: { ...draft.colors, [field]: next } });
+
+  const updateAsset = (group: "icon" | "logo", mode: "light" | "dark", next: string) =>
+    update({
+      ...draft,
+      assets: {
+        ...draft.assets,
+        [group]: { ...draft.assets[group], [mode]: next || undefined },
+      },
+    });
+
+  return (
+    <Card className={cn("overflow-hidden", className)}>
+      <CardHeader>
+        <div className="flex flex-wrap items-start justify-between gap-3">
+          <div>
+            <CardTitle>Brand picker</CardTitle>
+            <CardDescription>
+              Update identity, AppKit color tokens, document metadata, and email presentation.
+            </CardDescription>
+          </div>
+          <Button
+            type="button"
+            size="sm"
+            variant="outline"
+            onClick={() => {
+              setDraft(reset);
+              onChange(reset);
+            }}
+          >
+            Reset
+          </Button>
+        </div>
+      </CardHeader>
+      <CardContent className="space-y-6">
+        {resolvedPresets.length ? (
+          <section className="space-y-2" aria-label="Brand presets">
+            <Label>Presets</Label>
+            <div className="grid gap-2 sm:grid-cols-3">
+              {resolvedPresets.map((preset) => {
+                const active = object.deepEqual(current, preset.context);
+                return (
+                  <Button
+                    key={preset.id}
+                    type="button"
+                    variant={active ? "default" : "outline"}
+                    className="h-auto justify-start px-3 py-2 text-left"
+                    onClick={() => {
+                      setDraft(preset.context);
+                      onChange(preset.context);
+                    }}
+                  >
+                    <span>
+                      <span className="block text-sm font-medium">{preset.label}</span>
+                      {preset.description ? (
+                        <span className="block text-xs font-normal opacity-75">
+                          {preset.description}
+                        </span>
+                      ) : null}
+                    </span>
+                  </Button>
+                );
+              })}
+            </div>
+          </section>
+        ) : null}
+
+        <Separator />
+
+        <section className="space-y-3">
+          <div>
+            <h3 className="text-sm font-medium text-foreground">Identity</h3>
+            <p className="text-xs text-muted-foreground">
+              Used by navigation, metadata, and email.
+            </p>
+          </div>
+          <div className="grid gap-3 sm:grid-cols-2">
+            <div className="space-y-1.5">
+              <Label htmlFor={`${id}-name`}>Name</Label>
+              <Input
+                id={`${id}-name`}
+                value={draft.name}
+                onChange={(event) => updateIdentity("name", event.currentTarget.value)}
+              />
+            </div>
+            <div className="space-y-1.5">
+              <Label htmlFor={`${id}-short-name`}>Short name</Label>
+              <Input
+                id={`${id}-short-name`}
+                value={draft.shortName}
+                onChange={(event) => updateIdentity("shortName", event.currentTarget.value)}
+              />
+            </div>
+            <div className="space-y-1.5 sm:col-span-2">
+              <Label htmlFor={`${id}-tagline`}>Tagline</Label>
+              <Input
+                id={`${id}-tagline`}
+                value={draft.tagline}
+                onChange={(event) => updateIdentity("tagline", event.currentTarget.value)}
+              />
+            </div>
+          </div>
+        </section>
+
+        <Separator />
+
+        <section className="space-y-3">
+          <div>
+            <h3 className="text-sm font-medium text-foreground">Color system</h3>
+            <p className="text-xs text-muted-foreground">
+              Valid hex values are emitted immediately to the active brand provider.
+            </p>
+          </div>
+          <div className="grid gap-3 sm:grid-cols-2">
+            {COLOR_FIELDS.map(([field, label]) => (
+              <div key={field} className="space-y-1.5">
+                <Label htmlFor={`${id}-${field}`}>{label}</Label>
+                <div className="flex gap-2">
+                  <Input
+                    type="color"
+                    aria-label={`${label} color`}
+                    value={validColor(draft.colors[field], current.colors[field])}
+                    className="h-9 w-12 shrink-0 cursor-pointer p-1"
+                    onChange={(event) => updateColor(field, event.currentTarget.value)}
+                  />
+                  <Input
+                    id={`${id}-${field}`}
+                    value={draft.colors[field]}
+                    spellCheck={false}
+                    onChange={(event) => updateColor(field, event.currentTarget.value)}
+                  />
+                </div>
+              </div>
+            ))}
+          </div>
+        </section>
+
+        {showAssets ? (
+          <>
+            <Separator />
+            <section className="space-y-3">
+              <div>
+                <h3 className="text-sm font-medium text-foreground">Assets</h3>
+                <p className="text-xs text-muted-foreground">
+                  Package paths, data URLs, and hosted URLs are supported.
+                </p>
+              </div>
+              <div className="grid gap-3 sm:grid-cols-2">
+                {(["icon", "logo"] as const).flatMap((group) =>
+                  (["light", "dark"] as const).map((mode) => (
+                    <div key={`${group}-${mode}`} className="space-y-1.5">
+                      <Label htmlFor={`${id}-${group}-${mode}`}>
+                        {group === "icon" ? "Icon" : "Logo"} · {mode}
+                      </Label>
+                      <Input
+                        id={`${id}-${group}-${mode}`}
+                        value={draft.assets[group][mode] ?? ""}
+                        spellCheck={false}
+                        onChange={(event) => updateAsset(group, mode, event.currentTarget.value)}
+                      />
+                    </div>
+                  )),
+                )}
+                <div className="space-y-1.5 sm:col-span-2">
+                  <Label htmlFor={`${id}-favicon`}>Favicon</Label>
+                  <Input
+                    id={`${id}-favicon`}
+                    value={draft.assets.favicon}
+                    spellCheck={false}
+                    onChange={(event) =>
+                      update({
+                        ...draft,
+                        assets: { ...draft.assets, favicon: event.currentTarget.value },
+                      })
+                    }
+                  />
+                </div>
+              </div>
+            </section>
+          </>
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+}

package/src/react/index.ts

@@ -0,0 +1,2 @@
+export * from "./appkit-ui.ts";
+export * from "./brand-picker.tsx";

package/src/search/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. Single-index queries
+// delegate to AppKit's native `useAiSearchQuery`; universal search uses the
+// dbx-tools extension route.
+// 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/search/react/search-box.tsx

@@ -0,0 +1,153 @@
+// `SearchBox` is a drop-in search-as-you-type input for
+// Databricks AI Search. It wires an AppKit `Input` to the {@link useSearch}
+// hook and renders hits in a dropdown as the user types. AppKit's native
+// `aiSearch` client config supplies the index alias and query 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 { XIcon } from "lucide-react";
+import { useCallback, useState, type ReactNode } from "react";
+
+import { useSearch, type UseSearchOptions } from "./use-search.ts";
+import {
+  Badge,
+  Button,
+  Command,
+  CommandEmpty,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  Spinner,
+  cn,
+} from "../../react/index.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 (
+    <Command
+      shouldFilter={false}
+      className={cn("dbx-search-box h-auto overflow-visible bg-transparent", className)}
+      onKeyDown={(event) => {
+        if (event.key === "Escape") setOpen(false);
+      }}
+    >
+      <div className="dbx-search-box__field">
+        <CommandInput
+          value={query}
+          placeholder={placeholder}
+          aria-label={placeholder}
+          onValueChange={(value) => {
+            setQuery(value);
+            setOpen(true);
+          }}
+          onFocus={() => setOpen(true)}
+          onKeyDown={(event) => {
+            if (event.key === "Enter" && hits.length === 0) submit();
+          }}
+        />
+        {loading ? <Spinner className="dbx-search-box__spinner" /> : null}
+        {query ? (
+          <Button
+            variant="ghost"
+            size="icon"
+            aria-label="Clear search"
+            className="dbx-search-box__clear"
+            onClick={() => {
+              clear();
+              setOpen(false);
+            }}
+          >
+            <XIcon />
+          </Button>
+        ) : null}
+      </div>
+
+      {open && (query.trim() || error) ? (
+        <CommandList className="dbx-search-box__panel dbx-search-box__results">
+          {error ? <div className="dbx-search-box__error">{error}</div> : null}
+          {!error && !loading ? <CommandEmpty>No results</CommandEmpty> : null}
+          {hits.map((hit) => (
+            <CommandItem
+              key={`${hit.index ?? ""}:${hit.id}`}
+              value={JSON.stringify([hit.index ?? "", hit.id])}
+              className="dbx-search-box__hit"
+              onSelect={() => 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>
+              )}
+            </CommandItem>
+          ))}
+        </CommandList>
+      ) : null}
+    </Command>
+  );
+}

package/src/search/react/search-results.tsx

@@ -0,0 +1,76 @@
+// `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 type { ReactNode } from "react";
+
+import { Badge, cn } from "../../react/index.ts";
+
+/** 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>
+  );
+}