-
+ {/* The item's row is a FieldWrapper (or a full-width ObjectSection),
+ both of which are grid children of a FieldsGrid — inline mode's
+ `grid-cols-subgrid` resolves to `none` without one, collapsing
+ every item into a stacked column while the rest of the form stays
+ aligned. Fixed at one column: an item is a single row, and any
+ multi-column layout belongs to the item's own object body. */}
+
{ctx.render.renderFieldRow(
{
key: `${field.key}[${i}]`,
@@ -106,7 +119,7 @@ export function ArrayControl({
childCtx,
{ labelOverride: `Item ${i + 1}` },
)}
-
+
{!readOnly && (
}) {
+ const [value, setValue] = useState(initial);
+ return (
+ ("article")];
+}
+
+describe("x-array-display: cards", () => {
+ it("renders one card per item, titled from x-item rather than Item N", () => {
+ render( {}}
+ readOnly
+ showPreferencesMenu={false}
+ />,
+ );
+ expect(screen.queryByRole("button", { name: "Add parameter" })).not.toBeInTheDocument();
+ expect(screen.queryByRole("button", { name: "Remove namespace" })).not.toBeInTheDocument();
+ });
+
+ it("ignores the cards display for a plain string array", () => {
+ // A list of bare strings has no properties to summarize, so it stays on the
+ // compact tag editor rather than becoming a stack of untitled cards.
+ const schema: JsonSchemaObject = {
+ type: "object",
+ properties: {
+ tags: {
+ type: "array",
+ title: "Tags",
+ "x-array-display": "cards",
+ items: { type: "string" },
+ },
+ },
+ };
+ render(
+ {}} showPreferencesMenu={false} />,
+ );
+ expect(cards()).toHaveLength(0);
+ expect(screen.getByText("a")).toBeInTheDocument();
+ });
+});
diff --git a/packages/ui/src/components/json-schema-form-cards-array.tsx b/packages/ui/src/components/json-schema-form-cards-array.tsx
new file mode 100644
index 00000000..567cf84e
--- /dev/null
+++ b/packages/ui/src/components/json-schema-form-cards-array.tsx
@@ -0,0 +1,134 @@
+import { cn } from "../lib/utils";
+import { Icon } from "../data/Icon";
+import { UiAdd } from "../icons";
+import { Button } from "./button";
+import { appendInstancePath } from "./json-schema-form-errors";
+import {
+ addItemLabel,
+ emptyItemsCopy,
+ itemSummaryFor,
+ resolveItemSpec,
+} from "./json-schema-form-item-summary";
+import { ItemBadge, ItemRowActions, RequiredMark } from "./json-schema-form-item-row";
+import { inputSizeClass } from "./json-schema-form-size";
+import { TONE_EDGE_CLASS } from "./json-schema-form-tone";
+import {
+ duplicateIndex,
+ moveItem,
+ removeIndex,
+ seedFromSchema,
+ setIndex,
+} from "./json-schema-form-utils";
+import type { FieldControl, RenderContext } from "./json-schema-form-types";
+
+// CardsArray renders an object-item array as a stack of titled cards: every
+// item stays open, but each one is headed by what it actually is rather than
+// "Item 3", and carries the item type's hue on its left edge so a long stack is
+// scannable at a glance.
+//
+// It is the everything-visible counterpart to AccordionArray. Both read the
+// same `x-item` summary, so a consumer switches between them by changing
+// `x-array-display` alone — no second vocabulary to learn.
+export function CardsArray({
+ field,
+ ctx,
+ readOnly,
+}: {
+ field: FieldControl;
+ ctx: RenderContext;
+ readOnly: boolean;
+}) {
+ const items = Array.isArray(field.value) ? field.value : [];
+ const itemSchema = field.itemSchema ?? { type: "object" };
+ const spec = field.itemSpec ?? resolveItemSpec(field.schema, itemSchema);
+ const emptyCopy = emptyItemsCopy(spec, field.schema);
+ // The array's help mode governs its whole subtree, exactly as it does for the
+ // accordion: a card whose fields each carry a permanent two-line paragraph is
+ // back to the height the card layout exists to reclaim.
+ const childCtx: RenderContext = {
+ ...ctx,
+ readOnly,
+ depth: ctx.depth + 1,
+ ...(field.helpDisplay ? { layout: { ...ctx.layout, help: field.helpDisplay } } : {}),
+ };
+
+ function commit(next: unknown[]) {
+ field.onChange(next);
+ }
+
+ return (
+
+ {items.map((item, i) => {
+ const summary =
+ field.itemSummary?.({ item, index: i }) ??
+ itemSummaryFor({ item, index: i, spec, itemSchema });
+ return (
+
+
+
+ {i + 1}
+
+ {summary.title}
+
+ {summary.summary}
+
+ )}
+ {!readOnly && (
+ 0 ? { onUp: () => commit(moveItem(items, i, i - 1)) } : {})}
+ {...(i < items.length - 1
+ ? { onDown: () => commit(moveItem(items, i, i + 1)) }
+ : {})}
+ onDuplicate={() => commit(duplicateIndex(items, i))}
+ onRemove={() => commit(removeIndex(items, i))}
+ />
+ )}
+
+
+ {/* Recurse through the shared pipeline so consumer pre/post
+ extensions still apply to the item and its properties — and so
+ the item's own x-columns reaches its ObjectControl. */}
+ {ctx.render.renderFieldNodes(
+ {
+ key: `${field.key}[${i}]`,
+ prop: itemSchema,
+ required: false,
+ value: item,
+ onChange: (next) => commit(setIndex(items, i, next)),
+ instancePath: appendInstancePath(ctx.instancePath, i),
+ },
+ childCtx,
+ )?.value ?? null}
+
+
+ );
+ })}
+ {items.length === 0 && emptyCopy && (
+
{emptyCopy}
+ )}
+ {!readOnly && (
+
commit([...items, seedFromSchema(itemSchema)])}
+ >
+
+ )}
+
+ {glyph.icon != null &&
+ );
+}
+
+export function ItemBadge({ badge }: { badge?: ArrayItemSummary["badge"] }) {
+ if (!badge) return null;
+ return (
+
+ {badge.icon != null &&
+ );
+}
+
+export function RequiredMark() {
+ return (
+
+
+ );
+}
+
+export function ItemRowActions({
+ index,
+ title,
+ size,
+ onUp,
+ onDown,
+ onDuplicate,
+ onRemove,
+}: {
+ index: number;
+ title: string;
+ size: FormSize;
+ onUp?: () => void;
+ onDown?: () => void;
+ onDuplicate: () => void;
+ onRemove: () => void;
+}) {
+ // Hidden until the row is hovered or something inside it takes focus, so a
+ // long list is not a wall of permanently dim icons — but keyboard users see
+ // them the moment they arrive. Needs `group` on the item container.
+ const action = cn(
+ "inline-flex aspect-square items-center justify-center rounded text-muted-foreground hover:bg-accent hover:text-foreground disabled:opacity-30",
+ controlHeightClass[size],
+ );
+ return (
+
+
+
+
+
+
+
+
+
+
+ );
+}
diff --git a/packages/ui/src/components/json-schema-form-render.tsx b/packages/ui/src/components/json-schema-form-render.tsx
index 15e8e734..e6aa0d46 100644
--- a/packages/ui/src/components/json-schema-form-render.tsx
+++ b/packages/ui/src/components/json-schema-form-render.tsx
@@ -247,11 +247,13 @@ export function renderFieldRow(
// instead of cramming it into the inline value column.
// An accordion joins this list: crammed into the 600px inline value column it
// is unusable, and it needs the ObjectSection header to carry the array's own
- // title, required marker and help.
+ // title, required marker and help. Cards are the same shape of thing — a
+ // full-width stack of item panels — so they join it too.
if (
field.kind === "object" ||
field.layout === "table" ||
- field.arrayDisplay === "accordion"
+ field.arrayDisplay === "accordion" ||
+ field.arrayDisplay === "cards"
) {
return (
0)) {
return true;
}
- return prop["x-layout"] === "table" || prop["x-array-display"] === "accordion";
+ return (
+ prop["x-layout"] === "table" ||
+ prop["x-array-display"] === "accordion" ||
+ prop["x-array-display"] === "cards"
+ );
}
// renderApi is the RenderContext injection bundle: the root form stores it on
diff --git a/packages/ui/src/components/json-schema-form-resolve.ts b/packages/ui/src/components/json-schema-form-resolve.ts
index b5d44bc1..6a290645 100644
--- a/packages/ui/src/components/json-schema-form-resolve.ts
+++ b/packages/ui/src/components/json-schema-form-resolve.ts
@@ -112,7 +112,7 @@ function enumDisplay(prop: JsonSchemaProperty): EnumDisplay | undefined {
function arrayDisplay(prop: JsonSchemaProperty): ArrayDisplay | undefined {
const d = prop["x-array-display"];
- return d === "filter-pills" || d === "accordion" ? d : undefined;
+ return d === "filter-pills" || d === "accordion" || d === "cards" ? d : undefined;
}
// helpDisplay reads the per-field `x-help-display` override. Returns undefined
diff --git a/packages/ui/src/components/json-schema-form-types.ts b/packages/ui/src/components/json-schema-form-types.ts
index 0b2d336b..479c7c52 100644
--- a/packages/ui/src/components/json-schema-form-types.ts
+++ b/packages/ui/src/components/json-schema-form-types.ts
@@ -71,8 +71,10 @@ export interface JsonSchemaProperty {
// Force the enum presentation: "combobox" (default), "radio", "grid", or
// "segmented".
"x-enum-display"?: EnumDisplay;
- // Force the presentation for an enum-backed array. "filter-pills" renders
- // each enum item as a compact toggle; an empty stored array means all options.
+ // Force an array's presentation. "filter-pills" renders each enum item as a
+ // compact toggle (an empty stored array means all options); "accordion" and
+ // "cards" render object items as summary rows or titled cards, both reading
+ // `x-item` for the summary.
"x-array-display"?: ArrayDisplay;
// Force how this field's description is presented, overriding the form-level
// `FormLayout.help`. Defaults to "inline" (a paragraph under the control).
@@ -211,8 +213,11 @@ export type GridColumns = number | "auto";
// "hover" moves it behind a `?` beside the label, costing no vertical space.
export type HelpDisplay = "inline" | "hover";
-// How an array control renders when the item schema has enum options.
-export type ArrayDisplay = "filter-pills" | "accordion";
+// How an array control renders. "filter-pills" needs enum item options;
+// "accordion" and "cards" both need object items and both read `x-item` — the
+// accordion collapses every item to one line and opens one at a time, cards
+// keep every item open under a titled, hue-edged header.
+export type ArrayDisplay = "filter-pills" | "accordion" | "cards";
// ArrayItemSpec is the `x-item` extension on an ARRAY schema: it says how to
// summarize one element of this list in a collapsed row. Every value names a
diff --git a/packages/ui/src/components/unit-form-extension.test.tsx b/packages/ui/src/components/unit-form-extension.test.tsx
new file mode 100644
index 00000000..f1fa7541
--- /dev/null
+++ b/packages/ui/src/components/unit-form-extension.test.tsx
@@ -0,0 +1,163 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { JsonSchemaForm } from "./JsonSchemaForm";
+import {
+ createUnitFormExtensions,
+ formatUnitAwareValue,
+ parseUnitAwareValue,
+ type UnitInputKind,
+} from "./unit-form-extension";
+import type { JsonSchemaObject } from "./json-schema-form-types";
+
+const schema: JsonSchemaObject = {
+ type: "object",
+ properties: {
+ rows: {
+ type: "string",
+ title: "Rows",
+ pattern: "^[1-9][0-9]*$",
+ "x-clicky-unit": "count",
+ "x-input-suffix": "rows",
+ },
+ memory: {
+ type: "string",
+ title: "Memory",
+ pattern: "^[1-9][0-9]*$",
+ "x-clicky-unit": "bytes",
+ },
+ },
+};
+
+const value = { rows: "1000000", memory: "268435456" };
+const extensions = createUnitFormExtensions();
+
+describe("createUnitFormExtensions", () => {
+ it("displays canonical count and byte strings using human units", () => {
+ render(
+ = {
+ "": "B",
+ k: "KiB",
+ kb: "KiB",
+ m: "MiB",
+ mb: "MiB",
+ g: "GiB",
+ gb: "GiB",
+ t: "TiB",
+ tb: "TiB",
+ };
+ const canonical = aliases[normalized] ?? label;
+ return BYTE_SCALES.find((scale) => scale.label.toLowerCase() === canonical.toLowerCase());
+}
+
+export function parseUnitAwareValue(value: string, kind: UnitInputKind): string | null {
+ const match = value.trim().replaceAll(",", "").replaceAll("_", "").match(
+ /^(\d+(?:\.\d+)?|\.\d+)\s*([a-zA-Z]*)$/,
+ );
+ if (!match) return null;
+
+ const amount = match[1];
+ const scale = scaleForLabel(kind, match[2] ?? "");
+ if (!amount || !scale) return null;
+ const [whole, fraction = ""] = amount.split(".");
+ const denominator = 10n ** BigInt(fraction.length);
+ const numerator = BigInt(`${whole || "0"}${fraction}`) * scale.multiplier;
+ if (numerator % denominator !== 0n) return null;
+
+ const canonical = numerator / denominator;
+ return canonical > 0n ? String(canonical) : null;
+}
+
+function unitKind(field: FieldControl): UnitInputKind | null {
+ const unit = field.schema["x-clicky-unit"];
+ return unit === "count" || unit === "bytes" ? unit : null;
+}
+
+function steppedValue(value: unknown, direction: "decrease" | "increase"): string | null {
+ const canonical = canonicalInteger(value);
+ if (canonical === null) return null;
+ const integer = BigInt(canonical);
+ const next = direction === "increase" ? integer * 2n : integer / 2n;
+ return next > 0n ? String(next) : null;
+}
+
+export function createUnitFormExtensions(): { pre: PreExtension[] } {
+ const pre: PreExtension = (field) => {
+ const kind = unitKind(field);
+ if (!kind) return field;
+ return {
+ ...field,
+ value: formatUnitAwareValue(field.value, kind),
+ suffix: (
+ [] = [
{ key: "notes", label: "Notes", grow: true },
];
-function DataTableShowcase() {
+function DataTableShowcase(args: DataTableProps) {
const [timeFrom, setTimeFrom] = useState("now-24h");
const [timeTo, setTimeTo] = useState("now");
const [dateFrom, setDateFrom] = useState("");
@@ -241,10 +242,12 @@ function DataTableShowcase() {
return (
;
export const Default: Story = {};
+export const Playground: Story = {
+ args: {
+ showFullscreenControl: true,
+ fullscreenButtonLabel: "Open controlled table",
+ },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ await expect(
+ canvas.getByRole("button", { name: "Open controlled table" }),
+ ).toBeVisible();
+ },
+};
+
export const FewColumns: Story = {
render: () => ) => {
+ event.preventDefault();
+ event.stopPropagation();
+ if (!navigator.clipboard?.writeText) {
+ setCopyState("failed");
+ return;
+ }
+ try {
+ await navigator.clipboard.writeText(diagnosticReport(diagnostics));
+ setCopyState("copied");
+ } catch {
+ setCopyState("failed");
+ }
+ };
return (
@@ -41,10 +63,38 @@ export function ErrorDetails({ diagnostics, renderJsonContext }: ErrorDetailsPro
{diagnostics.message}
{(diagnostics.trace || diagnostics.time) && (
@@ -116,6 +166,23 @@ export function ErrorDetails({ diagnostics, renderJsonContext }: ErrorDetailsPro
);
}
+function diagnosticReport(diagnostics: ErrorDiagnostics): string {
+ const lines = [`Error: ${diagnostics.message}`];
+ if (diagnostics.trace) lines.push(`Trace: ${diagnostics.trace}`);
+ if (diagnostics.time) lines.push(`Time: ${diagnostics.time}`);
+ if (diagnostics.context.length > 0) {
+ lines.push(
+ "",
+ "Context:",
+ ...diagnostics.context.map(([label, value]) => `${label}: ${value}`),
+ );
+ }
+ if (diagnostics.stacktrace) {
+ lines.push("", "Stack trace:", diagnostics.stacktrace);
+ }
+ return lines.join("\n");
+}
+
export function PrettyStackTrace({ stacktrace }: { stacktrace: string }) {
const parsed = parseDiagnosticsStackTrace(stacktrace);
if (parsed.frames.length === 0) {
diff --git a/packages/ui/src/data/diagnostics/error-diagnostics.ts b/packages/ui/src/data/diagnostics/error-diagnostics.ts
index 45f5962e..1b35329a 100644
--- a/packages/ui/src/data/diagnostics/error-diagnostics.ts
+++ b/packages/ui/src/data/diagnostics/error-diagnostics.ts
@@ -35,9 +35,9 @@ export function normalizeErrorDiagnostics(
}
const record = objectRecord(value);
if (!record) return null;
- const nested = objectRecord(record.error) ?? objectRecord(record.diagnostics);
- if (nested && nested !== record) {
- return normalizeErrorDiagnostics(nested, fallback);
+ const nestedError = objectRecord(record.error);
+ if (nestedError && nestedError !== record) {
+ return normalizeErrorDiagnostics(nestedError, fallback);
}
const message =
firstString(record, ["error", "message", "msg", "reason", "detail", "details"]) ?? fallback;
@@ -45,7 +45,13 @@ export function normalizeErrorDiagnostics(
const stacktrace = firstString(record, ["stacktrace", "stack_trace", "stackTrace", "stack"]);
const time = firstString(record, ["time", "timestamp", "created_at"]);
const context = contextEntries(record.context);
- if (!message && !trace && !stacktrace && context.length === 0) return null;
+ if (!message && !trace && !stacktrace && !time && context.length === 0) {
+ const nestedDiagnostics = objectRecord(record.diagnostics);
+ if (nestedDiagnostics && nestedDiagnostics !== record) {
+ return normalizeErrorDiagnostics(nestedDiagnostics, fallback);
+ }
+ }
+ if (!message && !trace && !stacktrace && !time && context.length === 0) return null;
return {
message: message ?? "Action failed",
context,
diff --git a/packages/ui/src/data/query-browser/QueryBrowser.paging.test.tsx b/packages/ui/src/data/query-browser/QueryBrowser.paging.test.tsx
index a3385f4c..e7e5939d 100644
--- a/packages/ui/src/data/query-browser/QueryBrowser.paging.test.tsx
+++ b/packages/ui/src/data/query-browser/QueryBrowser.paging.test.tsx
@@ -195,4 +195,36 @@ describe("QueryBrowser paging and provider diagnostics", () => {
),
).toBeVisible();
});
+
+ it("renders Oops context returned with an execution error", async () => {
+ const execute = vi.fn().mockRejectedValue(
+ new QueryBrowserExecutionError("query failed", undefined, {
+ message: "query failed",
+ trace: "trace-query-1",
+ time: "2026-08-11T12:00:00Z",
+ context: [["connection", "tenant-x"]],
+ stacktrace: "query failed\n--- at example/query.go:42 runQuery",
+ }),
+ );
+ render(
+
,
+ );
+
+ fireEvent.click(screen.getByRole("button", { name: "Run" }));
+ const details = (
+ await screen.findByRole("button", { name: "Copy error details" })
+ ).closest("details");
+ expect(details).not.toBeNull();
+
+ fireEvent.click(within(details!).getByText("More details"));
+ expect(within(details!).getByText("trace-query-1")).toBeVisible();
+ expect(within(details!).getByText("tenant-x")).toBeVisible();
+ expect(within(details!).getByText("SELECT broken")).toBeVisible();
+ expect(within(details!).getByText(/example\/query\.go:42/)).toBeVisible();
+ });
});
diff --git a/packages/ui/src/data/query-browser/QueryBrowser.stories.tsx b/packages/ui/src/data/query-browser/QueryBrowser.stories.tsx
new file mode 100644
index 00000000..783efc7a
--- /dev/null
+++ b/packages/ui/src/data/query-browser/QueryBrowser.stories.tsx
@@ -0,0 +1,230 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, within } from "storybook/test";
+import type { JsonSchemaObject } from "../../components/json-schema-form-types";
+import type { DataTableServerColumn } from "../data-table-server-filters";
+import { QueryBrowser } from "./QueryBrowser";
+import {
+ QueryBrowserExecutionError,
+ type QueryBrowserRequest,
+ type QueryBrowserResult,
+} from "./QueryBrowser.types";
+
+const rows: Record
[] = [
+ {
+ observed_at: "2026-08-11T08:14:32Z",
+ service: "Checkout API",
+ status: "healthy",
+ region: "eu-west",
+ duration_ms: 84,
+ },
+ {
+ observed_at: "2026-08-11T08:14:21Z",
+ service: "Ledger Worker",
+ status: "degraded",
+ region: "us-east",
+ duration_ms: 413,
+ },
+ {
+ observed_at: "2026-08-11T08:13:58Z",
+ service: "Identity API",
+ status: "healthy",
+ region: "eu-west",
+ duration_ms: 126,
+ },
+ {
+ observed_at: "2026-08-11T08:13:44Z",
+ service: "Reporting API",
+ status: "failed",
+ region: "ap-south",
+ duration_ms: 1305,
+ },
+ {
+ observed_at: "2026-08-11T08:13:12Z",
+ service: "Checkout API",
+ status: "healthy",
+ region: "us-east",
+ duration_ms: 91,
+ },
+ {
+ observed_at: "2026-08-11T08:12:47Z",
+ service: "Ledger Worker",
+ status: "healthy",
+ region: "eu-west",
+ duration_ms: 204,
+ },
+];
+
+const columns: DataTableServerColumn[] = [
+ { name: "observed_at", label: "Observed", kind: "timestamp" },
+ {
+ name: "service",
+ label: "Service",
+ filterKey: "service",
+ filter: {
+ kind: "terms",
+ options: ["Checkout API", "Ledger Worker", "Identity API", "Reporting API"].map(
+ (value) => ({ value }),
+ ),
+ },
+ },
+ {
+ name: "status",
+ label: "Status",
+ kind: "status",
+ filterKey: "status",
+ filter: {
+ kind: "terms",
+ options: ["healthy", "degraded", "failed"].map((value) => ({ value })),
+ },
+ },
+ { name: "region", label: "Region" },
+ { name: "duration_ms", label: "Duration (ms)" },
+];
+
+const optionsSchema: JsonSchemaObject = {
+ type: "object",
+ properties: {
+ database: {
+ type: "string",
+ title: "Database",
+ enum: ["operations", "analytics"],
+ },
+ readOnly: { type: "boolean", title: "Read only" },
+ },
+};
+
+async function executeSampleQuery(
+ request: QueryBrowserRequest,
+): Promise {
+ const filtered = rows.filter((row) =>
+ Object.entries(request.filters ?? {}).every(([key, encoded]) => {
+ const value = String(row[key] ?? "");
+ const tokens = encoded.split(",").filter(Boolean);
+ const included = tokens.filter((token) => !token.startsWith("!"));
+ const excluded = tokens.filter((token) => token.startsWith("!")).map((token) => token.slice(1));
+ return (included.length === 0 || included.includes(value)) && !excluded.includes(value);
+ }),
+ );
+ const limit = request.pagination?.limit ?? 4;
+ const offset = request.pagination?.offset ?? 0;
+ const page = filtered.slice(offset, offset + limit);
+
+ return {
+ rows: page,
+ columns,
+ durationMs: 18,
+ pagination: {
+ mode: "offset",
+ limit,
+ offset,
+ hasMore: offset + limit < filtered.length,
+ total: filtered.length,
+ totalRelation: "eq",
+ consistency: "snapshot",
+ },
+ ...(request.debug
+ ? {
+ diagnostics: {
+ provider: "postgresql",
+ request: {
+ query: request.query,
+ options: request.options,
+ details: { transaction: "read-only", plan: "Index Scan" },
+ },
+ response: {
+ durationMs: 18,
+ returnedRows: page.length,
+ contentType: "application/json",
+ preview: JSON.stringify(page),
+ },
+ },
+ }
+ : {}),
+ };
+}
+
+const meta = {
+ title: "Data/QueryBrowser",
+ component: QueryBrowser,
+ parameters: {
+ layout: "fullscreen",
+ docs: {
+ description: {
+ component:
+ "A provider-neutral query workspace with CodeMirror editing, optional schema-driven options, remembered history, source-described filters, pagination, result details and provider diagnostics. The examples use an in-memory SQL executor, so no backend is required.",
+ },
+ },
+ },
+ argTypes: {
+ execute: { table: { disable: true } },
+ lookupFilterValues: { table: { disable: true } },
+ renderResults: { table: { disable: true } },
+ navigator: { table: { disable: true } },
+ },
+ render: (args) => (
+
+
+ ),
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+export const SqlResults: Story = {
+ args: {
+ id: "storybook-query-browser-sql",
+ title: "Service health",
+ language: "sql",
+ queryLabel: "PostgreSQL query",
+ initialQuery:
+ "SELECT observed_at, service, status, region, duration_ms\nFROM service_health\nORDER BY observed_at DESC",
+ optionsSchema,
+ initialOptions: { database: "operations", readOnly: true },
+ completion: {
+ kind: "sql",
+ dialect: "postgresql",
+ defaultSchema: "public",
+ schemas: [
+ {
+ name: "public",
+ relations: [
+ {
+ name: "service_health",
+ columns: columns.map((column) => ({ name: column.name })),
+ },
+ ],
+ },
+ ],
+ },
+ execute: executeSampleQuery,
+ },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ await userEvent.click(canvas.getByRole("button", { name: "Run" }));
+ await expect(canvas.findByText("Checkout API")).resolves.toBeVisible();
+ await expect(canvas.findByText("Page 1 of 2")).resolves.toBeVisible();
+ },
+};
+
+export const ProviderError: Story = {
+ args: {
+ id: "storybook-query-browser-error",
+ title: "Broken query",
+ language: "sql",
+ initialQuery: "SELECT missing_column FROM service_health",
+ execute: async () => {
+ throw new QueryBrowserExecutionError("query execution failed", {
+ provider: "postgresql",
+ request: { query: "SELECT missing_column FROM service_health" },
+ response: { details: { code: "42703" } },
+ error: "column missing_column does not exist",
+ });
+ },
+ },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ await userEvent.click(canvas.getByRole("button", { name: "Run" }));
+ await expect(canvas.findByText("query execution failed")).resolves.toBeVisible();
+ },
+};
diff --git a/packages/ui/src/data/query-browser/QueryBrowser.tsx b/packages/ui/src/data/query-browser/QueryBrowser.tsx
index c1032b73..78d48755 100644
--- a/packages/ui/src/data/query-browser/QueryBrowser.tsx
+++ b/packages/ui/src/data/query-browser/QueryBrowser.tsx
@@ -17,6 +17,7 @@ import {
type DataTableServerColumn,
} from "../data-table-server-filters";
import { ErrorDetails } from "../diagnostics/ErrorDetails";
+import type { ErrorDiagnostics } from "../diagnostics/error-diagnostics";
import {
queryBrowserEditorExtensions,
queryBrowserLanguageExtension,
@@ -64,6 +65,7 @@ export function QueryBrowser({
message: string;
query: string;
diagnostics?: QueryBrowserDiagnostics;
+ errorDetails?: ErrorDiagnostics;
} | null>(null);
const [pending, setPending] = useState(false);
const [debug, setDebug] = useState(false);
@@ -109,6 +111,9 @@ export function QueryBrowser({
...(err instanceof QueryBrowserExecutionError && err.diagnostics
? { diagnostics: err.diagnostics }
: {}),
+ ...(err instanceof QueryBrowserExecutionError && err.errorDetails
+ ? { errorDetails: err.errorDetails }
+ : {}),
});
} finally {
setPending(false);
@@ -414,8 +419,12 @@ export function QueryBrowser({
;
- completion?: QueryBrowserCompletion;
- onQueryChange?: (query: string) => void;
- onOptionsChange?: (options: Record) => void;
- navigator?: ReactNode;
+ title?: string | undefined;
+ language?: QueryBrowserLanguage | undefined;
+ initialQuery?: string | undefined;
+ queryLabel?: string | undefined;
+ optionsSchema?: JsonSchemaObject | undefined;
+ initialOptions?: Record | undefined;
+ completion?: QueryBrowserCompletion | undefined;
+ onQueryChange?: ((query: string) => void) | undefined;
+ onOptionsChange?: ((options: Record) => void) | undefined;
+ navigator?: ReactNode | undefined;
execute: (request: QueryBrowserRequest) => Promise;
- lookupFilterValues?: QueryBrowserFilterLookup;
- renderResults?: (context: QueryBrowserResultContext) => ReactNode;
- className?: string;
+ lookupFilterValues?: QueryBrowserFilterLookup | undefined;
+ renderResults?: ((context: QueryBrowserResultContext) => ReactNode) | undefined;
+ className?: string | undefined;
};
diff --git a/packages/ui/src/lib/string.test.ts b/packages/ui/src/lib/string.test.ts
index 855958e6..01524b68 100644
--- a/packages/ui/src/lib/string.test.ts
+++ b/packages/ui/src/lib/string.test.ts
@@ -1,5 +1,9 @@
import { describe, expect, it } from "vitest";
-import { stripLeadingSlashes, stripTrailingSlashes } from "./string";
+import {
+ stripLeadingSlashes,
+ stripSurroundingDashes,
+ stripTrailingSlashes,
+} from "./string";
describe("slash stripping", () => {
it("strips long leading and trailing slash runs", () => {
@@ -10,3 +14,12 @@ describe("slash stripping", () => {
expect(stripTrailingSlashes(slashes)).toBe("");
});
});
+
+describe("dash stripping", () => {
+ it("strips long leading and trailing dash runs", () => {
+ const dashes = "-".repeat(50_000);
+ expect(stripSurroundingDashes(`${dashes}slug${dashes}`)).toBe("slug");
+ expect(stripSurroundingDashes(dashes)).toBe("");
+ expect(stripSurroundingDashes("a-b")).toBe("a-b");
+ });
+});
diff --git a/packages/ui/src/lib/string.ts b/packages/ui/src/lib/string.ts
index bbd32864..80c87b8d 100644
--- a/packages/ui/src/lib/string.ts
+++ b/packages/ui/src/lib/string.ts
@@ -9,3 +9,13 @@ export function stripTrailingSlashes(value: string): string {
while (end > 0 && value[end - 1] === "/") end--;
return value.slice(0, end);
}
+
+// Linear scan instead of `.replace(/^-+|-+$/g, "")`: the anchored `-+`
+// alternatives backtrack polynomially on slugs made of many dashes.
+export function stripSurroundingDashes(value: string): string {
+ let start = 0;
+ let end = value.length;
+ while (start < end && value[start] === "-") start++;
+ while (end > start && value[end - 1] === "-") end--;
+ return value.slice(start, end);
+}
diff --git a/packages/ui/src/profiles.ts b/packages/ui/src/profiles.ts
new file mode 100644
index 00000000..2753806a
--- /dev/null
+++ b/packages/ui/src/profiles.ts
@@ -0,0 +1,73 @@
+/**
+ * Profile authoring: the editor, the wizard, and the query builder behind them.
+ *
+ * These components author a commons-db `query.Profile` — the shape shared by
+ * trace profiles, view specs and ad-hoc reports — so every app that stores
+ * profiles edits them through one UI instead of growing its own.
+ *
+ * Call configureProfiles({ schema, basePath }) once at startup: the schema is
+ * generated from commons-db's Go types and served by the host, and basePath is
+ * where that host mounts the profile service (default `/api/v1`).
+ */
+// profileEditorRaw is deliberately absent. ProfileEditor reaches it through
+// React.lazy so Monaco stays out of the initial chunk; re-exporting it here
+// would make every importer of this entry load Monaco eagerly, and Monaco is
+// an optional peer dependency a consumer may not have installed at all.
+// testSchema is a test fixture, not API.
+
+export * from "./profiles/catalogTree";
+export * from "./profiles/connectionBrowserModel";
+export * from "./profiles/connectionQueryWorkspace";
+export * from "./profiles/connectionQueryWorkspaceModel";
+export * from "./profiles/esFieldValues";
+export * from "./profiles/esParamMappingModel";
+export * from "./profiles/esParamMappingPill";
+export * from "./profiles/esParamOperandExtension";
+export * from "./profiles/esQueryBuilder";
+export * from "./profiles/esQueryBuilderExtension";
+export * from "./profiles/esQueryBuilderForm";
+export * from "./profiles/esQueryBuilderModel";
+export * from "./profiles/esQueryClauseGroup";
+export * from "./profiles/esQueryCompile";
+export * from "./profiles/esQueryConditionRow";
+export * from "./profiles/esQueryGroupModel";
+export * from "./profiles/esQueryOccur";
+export * from "./profiles/esQueryOperandEditors";
+export * from "./profiles/esQueryOperandModel";
+export * from "./profiles/esQueryOperators";
+export * from "./profiles/esQueryOutputEditor";
+export * from "./profiles/esQueryOutputModel";
+export * from "./profiles/esQueryPreview";
+export * from "./profiles/esQuerySortEditor";
+export * from "./profiles/esQuerySortModel";
+export * from "./profiles/esValueCombobox";
+export * from "./profiles/jsonPathSample";
+export * from "./profiles/jsonPathSampleRow";
+export * from "./profiles/profileApi";
+export * from "./profiles/profileBuilder";
+export * from "./profiles/profileBuilderExtension";
+export * from "./profiles/profileBuilderWorkspace";
+export * from "./profiles/profileColumnModel";
+export * from "./profiles/profileColumnPicker";
+export * from "./profiles/profileEditor";
+export * from "./profiles/profileEditorModel";
+export * from "./profiles/profileEditorPreview";
+export * from "./profiles/profileEditorRail";
+export * from "./profiles/profileEditorRoutes";
+export * from "./profiles/profileEditorSections";
+export * from "./profiles/profileFieldEditor";
+export * from "./profiles/profileFieldGrid";
+export * from "./profiles/profileFieldManager";
+export * from "./profiles/profileFieldState";
+export * from "./profiles/profileFieldTypes";
+export * from "./profiles/profileParamModel";
+export * from "./profiles/profileWizard";
+export * from "./profiles/profileWizardHelp";
+export * from "./profiles/profileWizardModel";
+export * from "./profiles/profileWizardQueryStep";
+export * from "./profiles/profileWizardSteps";
+export * from "./profiles/profileYaml";
+export * from "./profiles/prometheusResults";
+export * from "./profiles/queryRowLimits";
+export * from "./profiles/queryRowLimitsModel";
+export * from "./profiles/queryTargetPicker";
diff --git a/packages/ui/src/profiles/.widen.py b/packages/ui/src/profiles/.widen.py
new file mode 100644
index 00000000..ea0a2211
--- /dev/null
+++ b/packages/ui/src/profiles/.widen.py
@@ -0,0 +1,62 @@
+"""Widen optional properties to `?: T | undefined` in named type declarations.
+
+clicky-ui builds with exactOptionalPropertyTypes, where an optional property may
+be absent but not present-and-undefined. For the draft models and component
+props here that distinction is noise -- a React caller passing a possibly-absent
+value is ordinary -- and the package's own components already declare
+`prop?: T | undefined` (see data/CodeBlock.tsx). This aligns these declarations
+with that convention.
+
+It deliberately does NOT touch the places where absent-vs-undefined is real:
+those are the objects serialized to the server, and they were fixed to `delete`
+the key instead.
+"""
+
+import pathlib
+import re
+import sys
+
+TARGETS = {
+ "esQueryBuilderModel.ts": ["EsSearch", "EsSortBy", "EsCondition"],
+ "profileEditorModel.ts": ["ProfileSectionStatus"],
+ "profileWizardModel.ts": ["ProfileWizardDraft", "ProfileRowLimits", "ParamDraft"],
+ "esQueryPreview.tsx": ["EsCompilation"],
+ "connectionQueryWorkspace.tsx": ["ConnectionQueryWorkspaceProps"],
+}
+
+PROP = re.compile(r"^(\s+)([A-Za-z_$][\w$]*)\?: ([^;]+);$")
+
+
+def widen_block(lines, start):
+ """Widen `x?: T;` lines of the type literal opening at `start` until its `};`."""
+ depth = 0
+ changed = 0
+ for index in range(start, len(lines)):
+ depth += lines[index].count("{") - lines[index].count("}")
+ match = PROP.match(lines[index])
+ if match and "| undefined" not in match.group(3):
+ indent, name, type_text = match.groups()
+ lines[index] = f"{indent}{name}?: {type_text} | undefined;"
+ changed += 1
+ if depth <= 0 and index > start:
+ return index, changed
+ return len(lines) - 1, changed
+
+
+total = 0
+for filename, type_names in TARGETS.items():
+ path = pathlib.Path(filename)
+ if not path.exists():
+ sys.exit(f"missing {filename}")
+ lines = path.read_text().split("\n")
+ for type_name in type_names:
+ for index, line in enumerate(lines):
+ if re.match(rf"^export type {type_name} = .*\{{\s*$", line):
+ _, changed = widen_block(lines, index)
+ total += changed
+ print(f"{filename}:{type_name}: widened {changed}")
+ break
+ else:
+ print(f"{filename}:{type_name}: NOT FOUND")
+ path.write_text("\n".join(lines))
+print(f"total {total}")
diff --git a/packages/ui/src/profiles/ProfileEditor.stories.tsx b/packages/ui/src/profiles/ProfileEditor.stories.tsx
new file mode 100644
index 00000000..05ff71db
--- /dev/null
+++ b/packages/ui/src/profiles/ProfileEditor.stories.tsx
@@ -0,0 +1,145 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useMemo, type ComponentProps } from "react";
+import { expect, userEvent, within } from "storybook/test";
+import type { ResolvedOperation } from "../rpc/types";
+import type { OperationsApiClient } from "../rpc/useOperations";
+import { ProfileEditor } from "./profileEditor";
+import { configureProfiles } from "./profileApi";
+import { testProfileSchema } from "./testSchema";
+
+configureProfiles({ schema: testProfileSchema });
+
+const client: OperationsApiClient = {
+ async getOpenAPISpec() {
+ return {
+ openapi: "3.0.0",
+ info: { title: "Profile examples", version: "1.0.0" },
+ paths: {},
+ };
+ },
+ async executeCommand() {
+ return { success: true, exit_code: 0 };
+ },
+ async submitForm() {
+ return { success: true, exit_code: 0, message: "Profile saved" };
+ },
+};
+
+const action: ResolvedOperation = {
+ path: "/api/v1/profiles/{id}",
+ method: "put",
+ operation: {
+ operationId: "profile_update",
+ summary: "Update profile",
+ responses: { "200": { description: "Updated" } },
+ },
+};
+
+const initialValue = {
+ profile: "service-health",
+ namespace: "observability",
+ render: "table",
+ provider: { type: "sql", options: {} },
+ query:
+ "SELECT observed_at, service, status, duration_ms FROM service_health ORDER BY observed_at DESC",
+ params: [
+ {
+ name: "service",
+ label: "Service",
+ type: "string",
+ role: "filter",
+ },
+ ],
+ columns: [
+ {
+ name: "observed_at",
+ label: "Observed",
+ type: "datetime",
+ kind: "timestamp",
+ },
+ {
+ name: "service",
+ label: "Service",
+ type: "string",
+ filter: { kind: "terms", lookup: true },
+ },
+ {
+ name: "status",
+ label: "Status",
+ type: "string",
+ kind: "status",
+ },
+ ],
+};
+
+function ProfileEditorStory(props: ComponentProps) {
+ const queryClient = useMemo(
+ () =>
+ new QueryClient({
+ defaultOptions: { queries: { retry: false, gcTime: 0 } },
+ }),
+ [],
+ );
+ return (
+
+
+
+ );
+}
+
+const meta = {
+ title: "Profiles/ProfileEditor",
+ component: ProfileEditor,
+ parameters: {
+ layout: "fullscreen",
+ docs: {
+ description: {
+ component:
+ "The route-sized editor for a commons-db query profile. Its section rail, field grid, inspector and preview use the shared Workspace layout. Hosts inject the generated profile schema with `configureProfiles` and provide an `OperationsApiClient` for save and lookup operations; this example supplies both in memory.",
+ },
+ },
+ },
+ args: {
+ client,
+ action,
+ surfaceKey: "profile-service-health",
+ initialValue,
+ onClose: () => undefined,
+ onSuccess: () => undefined,
+ },
+ argTypes: {
+ client: { table: { disable: true } },
+ action: { table: { disable: true } },
+ initialValue: { table: { disable: true } },
+ onClose: { table: { disable: true } },
+ onSuccess: { table: { disable: true } },
+ },
+ render: (args) => ;
+
+export default meta;
+type Story = StoryObj;
+
+export const General: Story = {
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ await expect(canvas.getByText("Profile identity")).toBeVisible();
+ await expect(canvas.getByDisplayValue("service-health")).toBeVisible();
+ },
+};
+
+export const Columns: Story = {
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ await userEvent.click(
+ canvas.getByRole("button", { name: /^Columns Fields, labels, expressions/ }),
+ );
+ await expect(canvas.findByText("3 of 3 included")).resolves.toBeVisible();
+ await expect(
+ canvas.findByRole("textbox", { name: "Label for observed_at" }),
+ ).resolves.toBeVisible();
+ },
+};
diff --git a/packages/ui/src/profiles/catalogTree.tsx b/packages/ui/src/profiles/catalogTree.tsx
new file mode 100644
index 00000000..8fdb8448
--- /dev/null
+++ b/packages/ui/src/profiles/catalogTree.tsx
@@ -0,0 +1,153 @@
+import { Icon } from "../data/Icon";
+import { TreeNode } from "../data/TreeNode";
+import {
+ UiActivity,
+ UiDatabase,
+ UiLink,
+ UiNamespace,
+ UiSqlColumn,
+ UiSqlDatabase,
+ UiSqlIndex,
+ UiSqlView,
+ UiTable,
+} from "../icons";
+import type { CatalogNode } from "./connectionBrowserModel";
+
+export function CatalogTree({
+ nodes,
+ loading,
+ error,
+ databases,
+ database,
+ onDatabaseChange,
+ onSelect,
+}: {
+ nodes: CatalogNode[];
+ loading: boolean;
+ error: unknown;
+ databases: string[];
+ database: string;
+ onDatabaseChange: (database: string) => void;
+ onSelect: (node: CatalogNode) => void;
+}) {
+ return (
+
+
+ Catalog
+
+ {databases.length > 0 ? (
+
+ Database
+ onDatabaseChange(event.target.value)}
+ className="mt-1 h-8 w-full rounded-md border bg-background px-2 text-xs text-foreground"
+ >
+ {databases.map((name) => (
+
+ {name}
+
+ ))}
+
+
+ ) : null}
+ {loading && (
+
+ Loading catalog…
+
+ )}
+ {error ? (
+
+
Unable to load catalog
+
{catalogErrorMessage(error)}
+
+ ) : null}
+ {!loading && !error && nodes.length === 0 ? (
+
+ No catalog objects found.
+
+ ) : null}
+
+
+ {nodes.map((node) => (
+
item.id}
+ getChildren={(item) => item.children}
+ defaultOpen={(item) => item.kind === "schema"}
+ isSecondary={(item) => item.kind === "column"}
+ onSelect={(item) => {
+ if (item.query) onSelect(item);
+ }}
+ indentPx={14}
+ basePaddingPx={8}
+ renderRow={({ node: item }) => (
+
+ {item.label}
+
+ )}
+ />
+ ))}
+ ;
+ catalog?: boolean;
+ /**
+ * What a query runs against when the source picks one flat target — the
+ * `index` option. Set, the browser offers a target combobox instead of a
+ * catalog tree.
+ */
+ targetLabel?: string;
+ /**
+ * The row caps that apply when a profile declares none of its own: the page a
+ * caller gets by default, the largest page it may ask for, and where an
+ * all-row export stops. The query's own `limit` option is none of them.
+ */
+ rowLimits?: BrowserRowLimits;
+};
+
+/** The defaults the server serves, shown as what an unset cap inherits. */
+export type BrowserRowLimits = {
+ pageSize: number;
+ maxPageSize: number;
+ maxExportRows: number;
+};
+
+/** The caps a profile sets for itself; each unset one takes its default. */
+export type ProfileRowLimits = {
+ pageSize?: number;
+ maxPageSize?: number;
+ maxExportRows?: number;
+};
+
+export type TargetKind = "index" | "alias" | "data_stream" | "pattern";
+
+export type InspectionTarget = {
+ name: string;
+ kind: TargetKind;
+ /** The rotation wildcard this concrete index rolls up into. */
+ pattern?: string;
+ /** How many rotations a `pattern` target covers. */
+ count?: number;
+};
+
+export type CatalogNode = {
+ id: string;
+ label: string;
+ kind: string;
+ query?: string;
+ options?: Record;
+ children?: CatalogNode[];
+};
+
+export type InspectionField = {
+ name: string;
+ dataType?: string;
+ types?: string[];
+ searchable?: boolean;
+ aggregatable?: boolean;
+ conflicting?: boolean;
+};
+
+export type BrowserInspection = {
+ kind: "sql" | "opensearch";
+ dialect?: "postgresql" | "mysql" | "mssql" | "standard";
+ database?: string;
+ databases?: string[];
+ defaultSchema?: string;
+ schemas?: {
+ name: string;
+ relations: {
+ name: string;
+ type?: "table" | "view";
+ columns: InspectionField[];
+ }[];
+ }[];
+ targets?: InspectionTarget[];
+ nodes?: CatalogNode[];
+ selected?: {
+ target: InspectionTarget;
+ fields: InspectionField[];
+ };
+ truncated?: boolean;
+ truncateReason?: string;
+};
+
+export type ConnectionProfileActionRenderer = (context: {
+ connectionName: string;
+ providerType: string;
+ providerOptions?: Record;
+}) => ReactNode;
+
+/**
+ * savedConnectionID reads the id out of a `connection://` reference. An
+ * inline URL has no id, and so no catalog to browse — hence null rather than a
+ * guess.
+ */
+export function savedConnectionID(value: string | undefined): string | null {
+ const prefix = "connection://";
+ if (!value?.startsWith(prefix)) return null;
+ return value.slice(prefix.length).trim() || null;
+}
+
+export function browserBaseUrl(connectionID: string): string {
+ return profileApiPath(`connection/${encodeURIComponent(connectionID)}/browser`);
+}
+
+export async function fetchJSON(url: string, init?: RequestInit): Promise {
+ const response = await fetch(url, init);
+ if (!response.ok) {
+ const body = await response.text();
+ const fallback = body.trim() || `request failed: ${response.status}`;
+ try {
+ const parsed = JSON.parse(body) as {
+ error?: unknown;
+ diagnostics?: QueryBrowserDiagnostics;
+ };
+ if (typeof parsed.error === "string") {
+ const errorDetails = normalizeErrorDiagnostics(parsed, parsed.error);
+ throw new QueryBrowserExecutionError(
+ errorDetails?.message ?? parsed.error,
+ parsed.diagnostics,
+ errorDetails ?? undefined,
+ );
+ }
+ } catch (error) {
+ if (error instanceof QueryBrowserExecutionError) throw error;
+ }
+ throw new Error(fallback);
+ }
+ return response.json() as Promise;
+}
+
+/**
+ * Rotations lead: a cluster with fifty-three daily jaeger indexes has one
+ * target an author actually means, and it is `jaeger-span-*`. The concrete
+ * indexes stay listed last so a single day is still reachable.
+ */
+const targetGroups: { kind: TargetKind; label: string }[] = [
+ { kind: "pattern", label: "Index patterns" },
+ { kind: "alias", label: "Aliases" },
+ { kind: "data_stream", label: "Data streams" },
+ { kind: "index", label: "Indexes" },
+];
+
+export function openSearchIndexOptions(
+ inspection?: BrowserInspection,
+): ComboboxOption[] {
+ if (inspection?.kind !== "opensearch") return [];
+ const targets = inspection.targets ?? [];
+ return targetGroups.flatMap(({ kind, label }) =>
+ targets
+ .filter((target) => target.kind === kind)
+ .map((target) => ({
+ value: target.name,
+ label: target.count ? `${target.name} · ${target.count} indexes` : target.name,
+ selectedLabel: target.name,
+ group: label,
+ title: target.count
+ ? `${target.name} · ${target.count} rotated indexes`
+ : `${target.name} · ${target.kind.replace("_", " ")}`,
+ })),
+ );
+}
+
+/**
+ * openSearchTargetKind resolves how to inspect a picked target. An undiscovered
+ * name containing a wildcard is a pattern by construction — the server inspects
+ * it without requiring it to have been enumerated.
+ */
+export function openSearchTargetKind(
+ inspection: BrowserInspection | undefined,
+ name: string,
+): string {
+ const discovered = (inspection?.targets ?? []).find(
+ (target) => target.name === name,
+ );
+ if (discovered) return discovered.kind;
+ return name.includes("*") ? "pattern" : "";
+}
+
+/**
+ * withTarget applies a picked target over a host's options, clearing both keys
+ * when the picker is emptied so a stale index cannot survive the selection.
+ */
+export function withTarget(
+ options: Record,
+ target: { index: string; targetKind: string } | undefined,
+): Record {
+ if (!target) return options;
+ const next = { ...options };
+ if (target.index) {
+ next.index = target.index;
+ next.targetKind = target.targetKind;
+ } else {
+ delete next.index;
+ delete next.targetKind;
+ }
+ return next;
+}
+
+/**
+ * queryBrowserOptionsSchema is what the inline options form edits — the leftover
+ * options, once the navigator has claimed the ones that belong with the query.
+ * The target has its own combobox, and where the source has a structured search
+ * the builder owns both the search and the limit it returns, so none of the
+ * three is rendered a second time as a generic field.
+ */
+export function queryBrowserOptionsSchema(
+ descriptor: BrowserDescriptor,
+): JsonSchemaObject | undefined {
+ if (!descriptor.optionsSchema) return undefined;
+ const properties = { ...descriptor.optionsSchema.properties };
+ if (properties.search) {
+ delete properties.search;
+ delete properties.limit;
+ }
+ if (descriptor.targetLabel) delete properties.index;
+ return { ...descriptor.optionsSchema, properties };
+}
+
+export function completionForInspection(
+ inspection?: BrowserInspection,
+ selectedInspection?: BrowserInspection,
+): QueryBrowserCompletion | undefined {
+ if (inspection?.kind === "sql" && inspection.dialect) {
+ return {
+ kind: "sql",
+ dialect: inspection.dialect,
+ ...(inspection.defaultSchema
+ ? { defaultSchema: inspection.defaultSchema }
+ : {}),
+ schemas: (inspection.schemas ?? []).map((schema) => ({
+ name: schema.name,
+ relations: schema.relations.map((relation) => ({
+ name: relation.name,
+ ...(relation.type ? { type: relation.type } : {}),
+ columns: relation.columns.map((column) => ({
+ name: column.name,
+ types: column.dataType ? [column.dataType] : [],
+ })),
+ })),
+ })),
+ };
+ }
+ if (
+ selectedInspection?.kind === "opensearch" &&
+ selectedInspection.selected
+ ) {
+ return {
+ kind: "json-fields",
+ vocabulary: "opensearch",
+ fields: selectedInspection.selected.fields,
+ };
+ }
+ return undefined;
+}
+
+/**
+ * mergeProviderOptions layers the option sources a browser draws on, in
+ * increasing precedence, and pins the active database when there is one.
+ * `targetKind` only tells the inspection endpoint which field mappings to
+ * fetch, so it is dropped unless the caller is feeding the browser itself.
+ */
+export function mergeProviderOptions(input: {
+ layers: Array | undefined>;
+ database?: string;
+ keepTargetKind?: boolean;
+}): Record {
+ const merged: Record = {};
+ for (const layer of input.layers) Object.assign(merged, layer ?? {});
+ if (input.database) merged.database = input.database;
+ if (!input.keepTargetKind) delete merged.targetKind;
+ return merged;
+}
+
+export type InspectionScope = {
+ /** Query-cache namespace, so each host keeps its own inspection cache. */
+ cacheKey: string;
+ id: string;
+ baseUrl: string;
+ enabled: boolean;
+ /** The database the author picked; empty means the connection's default. */
+ database: string;
+ /** A database carried by the stored provider options, tried before the default. */
+ fallbackDatabase?: string;
+ /** The selected index, alias or data stream. */
+ target: string;
+ /** An explicit target kind; resolved from the catalog when absent. */
+ targetKind?: string;
+};
+
+export type Inspection = {
+ data?: BrowserInspection | undefined;
+ nodes: CatalogNode[];
+ databases: string[];
+ activeDatabase: string;
+ /** The database to send with a query — empty unless the source is SQL. */
+ sqlDatabase: string;
+ targetKind: string;
+ loading: boolean;
+ error: unknown;
+ completion?: QueryBrowserCompletion | undefined;
+};
+
+/**
+ * useInspection resolves the catalog for a browser: the base inspection, the
+ * per-database one a SQL author switched to, and the per-target field mappings
+ * an OpenSearch author needs for completion.
+ */
+export function useInspection(scope: InspectionScope): Inspection {
+ const { cacheKey, id, baseUrl } = scope;
+ const base = useQuery({
+ queryKey: [cacheKey, id],
+ queryFn: () => fetchJSON(`${baseUrl}/inspect`),
+ enabled: scope.enabled,
+ retry: 0,
+ staleTime: 5 * 60_000,
+ });
+ const switchedDatabase =
+ scope.database !== "" && scope.database !== base.data?.database;
+ const database = useQuery({
+ queryKey: [cacheKey, id, scope.database],
+ queryFn: () => {
+ const params = new URLSearchParams({ database: scope.database });
+ return fetchJSON(`${baseUrl}/inspect?${params}`);
+ },
+ enabled: base.data?.kind === "sql" && switchedDatabase,
+ retry: 0,
+ staleTime: 5 * 60_000,
+ });
+ const active = switchedDatabase ? database : base;
+ const data = active.data ?? base.data;
+
+ const targetKind =
+ scope.targetKind ??
+ data?.targets?.find((target) => target.name === scope.target)?.kind ??
+ "";
+ const target = useQuery({
+ queryKey: [cacheKey, id, targetKind, scope.target],
+ queryFn: () => {
+ const params = new URLSearchParams({
+ target: scope.target,
+ targetKind,
+ });
+ return fetchJSON(`${baseUrl}/inspect?${params}`);
+ },
+ enabled: data?.kind === "opensearch" && scope.target !== "" && targetKind !== "",
+ retry: 0,
+ staleTime: 5 * 60_000,
+ });
+
+ const activeDatabase =
+ scope.database || scope.fallbackDatabase || data?.database || "";
+ const completion = useMemo(
+ () => completionForInspection(data, target.data),
+ [data, target.data],
+ );
+ return {
+ data,
+ nodes: data?.nodes ?? [],
+ databases: base.data?.databases ?? [],
+ activeDatabase,
+ sqlDatabase: data?.kind === "sql" ? activeDatabase : "",
+ targetKind,
+ loading: active.isLoading,
+ error: active.error,
+ completion,
+ };
+}
diff --git a/packages/ui/src/profiles/connectionQueryWorkspace.test.tsx b/packages/ui/src/profiles/connectionQueryWorkspace.test.tsx
new file mode 100644
index 00000000..b5537935
--- /dev/null
+++ b/packages/ui/src/profiles/connectionQueryWorkspace.test.tsx
@@ -0,0 +1,224 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+import type { BrowserDescriptor, Inspection } from "./connectionBrowserModel";
+import { ConnectionQueryWorkspace } from "./connectionQueryWorkspace";
+import { initialNavigatorTab, navigatorTabs, supportsQueryBuilder } from "./connectionQueryWorkspaceModel";
+import { EsCompileRequest } from "./esQueryCompile";
+
+// The compile request only leaves the browser once effects run, which server
+// rendering never does — so the wiring is asserted on what the hook was handed.
+const compileInputs = vi.hoisted(() => [] as EsCompileRequest[]);
+vi.mock("./esQueryCompile", async (importOriginal) => {
+ const original = await importOriginal();
+ return {
+ ...original,
+ useCompiledSearch: (input: EsCompileRequest) => {
+ compileInputs.push(input);
+ return original.useCompiledSearch(input);
+ },
+ };
+});
+
+const searchSchema = {
+ type: "object" as const,
+ properties: {
+ search: {
+ type: "object" as const,
+ "x-clicky-component": "es-query-builder",
+ "x-es-operators": [
+ { op: "term", label: "term", arity: "single", fieldTypes: ["keyword"] },
+ ],
+ },
+ },
+};
+
+const openSearch: BrowserDescriptor = {
+ kind: "query",
+ provider: "opensearch",
+ language: "json",
+ catalog: true,
+ targetLabel: "Index",
+ optionsSchema: searchSchema,
+};
+
+const sql: BrowserDescriptor = {
+ kind: "query",
+ provider: "sql",
+ language: "sql",
+ catalog: true,
+};
+
+describe("supportsQueryBuilder", () => {
+ it("accepts a source whose options schema carries an operator catalog", () => {
+ expect(supportsQueryBuilder(openSearch)).toBe(true);
+ });
+
+ it("rejects a source with no options schema", () => {
+ expect(supportsQueryBuilder(sql)).toBe(false);
+ });
+
+ it("rejects an options schema that describes no structured search", () => {
+ expect(
+ supportsQueryBuilder({
+ ...openSearch,
+ optionsSchema: { type: "object", properties: { index: { type: "string" } } },
+ }),
+ ).toBe(false);
+ });
+});
+
+describe("navigatorTabs", () => {
+ it("offers the two authoring modes as tabs, form first", () => {
+ expect(navigatorTabs({ descriptor: openSearch, builder: true })).toEqual([
+ { id: "form", label: "Form" },
+ { id: "json", label: "JSON" },
+ ]);
+ });
+
+ it("keeps the catalog tab for a hierarchical source with a builder", () => {
+ expect(
+ navigatorTabs({
+ descriptor: { ...openSearch, targetLabel: undefined },
+ builder: true,
+ }),
+ ).toEqual([
+ { id: "catalog", label: "Catalog" },
+ { id: "form", label: "Form" },
+ { id: "json", label: "JSON" },
+ ]);
+ });
+
+ it("offers Catalog alone for a source with no structured search", () => {
+ expect(navigatorTabs({ descriptor: sql, builder: false })).toEqual([
+ { id: "catalog", label: "Catalog" },
+ ]);
+ });
+
+ it("offers no tabs when the target picker is the whole navigator", () => {
+ expect(navigatorTabs({ descriptor: openSearch, builder: false })).toEqual([]);
+ });
+
+ it("offers no navigator when there is neither a catalog nor a builder", () => {
+ expect(
+ navigatorTabs({ descriptor: { ...sql, catalog: false }, builder: false }),
+ ).toEqual([]);
+ });
+});
+
+describe("initialNavigatorTab", () => {
+ it("starts in the form so filters are always built, not opted into", () => {
+ expect(
+ initialNavigatorTab({
+ tabs: navigatorTabs({ descriptor: openSearch, builder: true }),
+ search: undefined,
+ query: "",
+ }),
+ ).toBe("form");
+ });
+
+ it("opens a stored specification in the form", () => {
+ expect(
+ initialNavigatorTab({
+ tabs: navigatorTabs({ descriptor: openSearch, builder: true }),
+ search: {},
+ query: "",
+ }),
+ ).toBe("form");
+ });
+
+ it("opens a stored raw query in JSON rather than discarding it", () => {
+ expect(
+ initialNavigatorTab({
+ tabs: navigatorTabs({ descriptor: openSearch, builder: true }),
+ search: undefined,
+ query: '{"query":{"term":{"level":"error"}}}',
+ }),
+ ).toBe("json");
+ });
+
+ it("treats the descriptor's own starter query as nothing to preserve", () => {
+ expect(
+ initialNavigatorTab({
+ tabs: navigatorTabs({ descriptor: openSearch, builder: true }),
+ search: undefined,
+ query: '{"query":{"match_all":{}}}',
+ defaultQuery: '{"query":{"match_all":{}}}',
+ }),
+ ).toBe("form");
+ });
+
+ it("falls back to the only tab a builder-less source has", () => {
+ expect(
+ initialNavigatorTab({
+ tabs: navigatorTabs({ descriptor: sql, builder: false }),
+ search: undefined,
+ query: "SELECT 1",
+ }),
+ ).toBe("catalog");
+ });
+});
+
+// The preview is compiled server-side, so an operand that interpolates
+// {{.params.…}} resolves only if the host's parameter values travel with the
+// specification. Without them the panel shows the compiler's refusal to guess.
+describe("ConnectionQueryWorkspace compilation", () => {
+ const inspection: Inspection = {
+ nodes: [],
+ databases: [],
+ activeDatabase: "",
+ sqlDatabase: "",
+ targetKind: "index",
+ loading: false,
+ error: undefined,
+ };
+
+ const renderWorkspace = (extra: Record) => {
+ compileInputs.length = 0;
+ renderToStaticMarkup(
+
+ {}}
+ query=""
+ onQueryChange={() => {}}
+ options={{ index: "logs-*" }}
+ onOptionsChange={() => {}}
+ onCatalogSelect={() => {}}
+ search={{
+ query: {
+ op: "term",
+ field: "service.name",
+ value: "{{.params.service}}",
+ },
+ }}
+ onSearchChange={() => {}}
+ compileBaseUrl="/api/v1/connection/abc/browser"
+ execute={async () => ({ rows: [] })}
+ {...extra}
+ />
+ ,
+ );
+ return compileInputs;
+ };
+
+ it("compiles the specification against the host's parameter values", () => {
+ const inputs = renderWorkspace({
+ params: [{ name: "service" }, { name: "since", role: "time-from" }],
+ paramValues: { service: "payments", since: "now-1h" },
+ paramRoles: { since: "time-from" },
+ });
+ expect(inputs.length).toBeGreaterThan(0);
+ expect(inputs[0]?.params).toEqual({ service: "payments", since: "now-1h" });
+ expect(inputs[0]?.roles).toEqual({ since: "time-from" });
+ });
+
+ it("sends no parameter values when the host declares none", () => {
+ const inputs = renderWorkspace({});
+ expect(inputs.length).toBeGreaterThan(0);
+ expect(inputs[0]?.params).toBeUndefined();
+ });
+});
diff --git a/packages/ui/src/profiles/connectionQueryWorkspace.tsx b/packages/ui/src/profiles/connectionQueryWorkspace.tsx
new file mode 100644
index 00000000..a406239c
--- /dev/null
+++ b/packages/ui/src/profiles/connectionQueryWorkspace.tsx
@@ -0,0 +1,306 @@
+/**
+ * The single query-browser host. The connection browser, the profile wizard and
+ * the profile-edit builder all render this: they own where the query and the
+ * options are stored and what a run means, and this owns the browser itself —
+ * the catalog navigator, the structured filter builder, the completion, and the
+ * descriptor's result view.
+ */
+
+import type { JsonSchemaObject } from "../components/json-schema-form-types";
+import { LogsTable } from "../data/LogsTable";
+import { QueryBrowser } from "../data/query-browser/QueryBrowser";
+import type { QueryBrowserFilterLookup, QueryBrowserRequest, QueryBrowserResult, QueryBrowserResultContext } from "../data/query-browser/QueryBrowser.types";
+import { Tabs } from "../layout/Tabs";
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import { CatalogTree } from "./catalogTree";
+import {
+ withTarget,
+ type BrowserDescriptor,
+ type CatalogNode,
+ type Inspection,
+ type ProfileRowLimits
+} from "./connectionBrowserModel";
+import { makeFieldValueLookup } from "./esFieldValues";
+import { EsQueryBuilder } from "./esQueryBuilder";
+import {
+ toBuilderMode,
+ toRawMode,
+ type EsSearch,
+ type QueryModeTransition
+} from "./esQueryBuilderModel";
+import {
+ esBuilderVocabulary
+ } from "./esQueryOperators";
+import { PrometheusResults } from "./prometheusResults";
+import { QueryRowLimits } from "./queryRowLimits";
+import { QueryTargetPicker } from "./queryTargetPicker";
+import type { ParamMappingEdit } from "./esParamMappingModel";
+import type { ParamDraft } from "./profileWizardModel";
+import { initialNavigatorTab, navigatorTabs, supportsQueryBuilder } from "./connectionQueryWorkspaceModel";
+import { esQueryFields } from "./esQueryBuilderForm";
+import { useCompiledSearch } from "./esQueryCompile";
+
+
+export type ConnectionQueryWorkspaceProps = {
+ id: string;
+ title: string;
+ descriptor: BrowserDescriptor;
+ inspection: Inspection;
+ onDatabaseChange: (database: string) => void;
+ query: string;
+ onQueryChange?: (query: string) => void | undefined;
+ options: Record;
+ onOptionsChange: (options: Record) => void;
+ onCatalogSelect: (node: CatalogNode) => void;
+ optionsSchema?: JsonSchemaObject | undefined;
+ /**
+ * The structured specification this host stores, when it stores one.
+ * `undefined` means the raw query is the artifact.
+ */
+ search?: EsSearch | undefined;
+ /**
+ * Every change reports the specification and the raw query together, and one
+ * of the two is always empty. The host stores both in one write, so it can
+ * never end up holding a specification and a query at once — a state the
+ * server rejects.
+ */
+ onSearchChange?: (transition: QueryModeTransition) => void | undefined;
+ /**
+ * The row caps the edited profile sets for itself. They are profile settings,
+ * not provider options, so they are stored beside the query rather than
+ * through `onOptionsChange`. A host that edits no profile — the connection
+ * browser — passes neither, and the caps are then not offered at all.
+ */
+ limits?: ProfileRowLimits | undefined;
+ onLimitsChange?: (limits: ProfileRowLimits | undefined) => void;
+ /** Declared profile parameters an operand can bind to. */
+ params?: ParamDraft[] | undefined;
+ onParamMappingChange?: (edit: ParamMappingEdit) => void | undefined;
+ /**
+ * What those parameters currently resolve to. The server binds a {param:…}
+ * operand from them and interpolates a {{.params.…}} one, so without values
+ * the preview shows template text — or the compiler's refusal to guess.
+ */
+ paramValues?: Record | undefined;
+ /** Those parameters' roles, so the compiled preview folds them as a run would. */
+ paramRoles?: Record | undefined;
+ /** Where POST /compile lives. Empty leaves the preview unresolved. */
+ compileBaseUrl?: string | undefined;
+ execute: (request: QueryBrowserRequest) => Promise;
+ /**
+ * Answers a filter's value type-ahead. Absent leaves every filter the source
+ * described showing only the values the result itself carried.
+ */
+ lookupFilterValues?: QueryBrowserFilterLookup | undefined;
+ renderResults?: (context: QueryBrowserResultContext) => ReactNode | undefined;
+ className?: string | undefined;
+};
+
+export function ConnectionQueryWorkspace({
+ id,
+ title,
+ descriptor,
+ inspection,
+ onDatabaseChange,
+ query,
+ onQueryChange,
+ options,
+ onOptionsChange,
+ onCatalogSelect,
+ optionsSchema,
+ search,
+ onSearchChange,
+ limits,
+ onLimitsChange,
+ params,
+ onParamMappingChange,
+ paramValues,
+ paramRoles,
+ compileBaseUrl = "",
+ execute,
+ lookupFilterValues,
+ renderResults,
+ className
+}: ConnectionQueryWorkspaceProps) {
+ const builder = Boolean(onSearchChange) && supportsQueryBuilder(descriptor);
+ const tabs = navigatorTabs({ descriptor, builder });
+ const [tab, setTab] = useState(() =>
+ initialNavigatorTab({
+ tabs,
+ search,
+ query,
+ ...(descriptor.defaultQuery ? { defaultQuery: descriptor.defaultQuery } : {})
+ }),
+ );
+ // Picking a target has to reach the browser, which only resyncs its options
+ // when `initialOptions` changes identity. The pick is layered here rather than
+ // round-tripped through the host, so an options-form keystroke — which the
+ // host also stores — cannot resync the browser out from under the author.
+ const [picked, setPicked] = useState>();
+ // What the browser last reported, so a pick keeps the author's other edits.
+ const edited = useRef(options);
+ const seed = useRef(options);
+ if (seed.current !== options) {
+ seed.current = options;
+ edited.current = options;
+ if (picked) setPicked(undefined);
+ }
+ const browserOptions = picked ?? options;
+ const applyOptions = (next: Record) => {
+ edited.current = next;
+ setPicked(next);
+ onOptionsChange(next);
+ };
+ const compilation = useCompiledSearch({
+ baseUrl: compileBaseUrl,
+ search: search ?? {},
+ ...(paramValues ? { params: paramValues } : {}),
+ ...(paramRoles ? { roles: paramRoles } : {}),
+ enabled: Boolean(search) && compileBaseUrl !== ""
+ });
+ const values = makeFieldValueLookup({
+ baseUrl: compileBaseUrl,
+ index: String(browserOptions.index ?? ""),
+ ...(paramValues ? { params: paramValues } : {}),
+ ...(paramRoles ? { roles: paramRoles } : {})
+ });
+
+ // While a specification is active the editor mirrors what it compiles to. It
+ // is a preview, not an input: the query is not stored alongside the spec, so
+ // there is no keystroke for a compile to overwrite.
+ const specMode = search !== undefined;
+ const active = tabs.some((entry) => entry.id === tab) ? tab : tabs[0]?.id;
+
+ // The form tab is the specification, so being on it means holding one. A tab
+ // that stores nothing would leave the builder rendering a query it cannot
+ // edit, and this is also what makes filters the default rather than an opt-in.
+ useEffect(() => {
+ if (active === "form" && onSearchChange && search === undefined) {
+ onSearchChange(toBuilderMode());
+ }
+ }, [active, onSearchChange, search]);
+
+ // Switching tabs is the mode switch. Each mode stores its own artifact and the
+ // server rejects holding both, so leaving the form hands the raw editor the
+ // DSL the specification last compiled to and drops the specification.
+ const selectTab = (next: string) => {
+ if (next === "json" && search && onSearchChange) {
+ onSearchChange(toRawMode(search, compilation.query, query));
+ }
+ setTab(next);
+ };
+
+ return (
+ {
+ edited.current = next;
+ onOptionsChange(next);
+ }}
+ className={className}
+ navigator={
+ tabs.length === 0 && !descriptor.targetLabel ? undefined : (
+
+ {descriptor.targetLabel ? (
+
+ applyOptions(withTarget(edited.current, { index, targetKind }))
+ }
+ />
+ ) : null}
+ {builder ? (
+
+ applyOptions({ ...edited.current, limit })
+ }
+ {...(descriptor.rowLimits
+ ? { defaults: descriptor.rowLimits }
+ : {})}
+ {...(limits ? { limits } : {})}
+ {...(onLimitsChange ? { onLimitsChange } : {})}
+ />
+ ) : null}
+ {tabs.length > 1 ? (
+ onSearchChange({ search: next, query: "" })}
+ fields={esQueryFields(inspection.completion)}
+ vocabulary={esBuilderVocabulary(descriptor.optionsSchema)}
+ {...(params ? { params } : {})}
+ {...(onParamMappingChange
+ ? { onMappingChange: onParamMappingChange }
+ : {})}
+ {...(values ? { values } : {})}
+ compilation={compilation}
+ />
+ ) : active === "json" ? (
+
+ The {descriptor.queryLabel ?? "query"} editor holds the query.
+ Switch back to Form to build it from filters — the raw query is
+ dropped then, since only one of the two is stored.
+
+ ) : active === "catalog" ? (
+ ;
+};
+
+/** A host's lookup, bound to a connection and an index. */
+export type FieldValuesSource = (request: {
+ field: string;
+ search?: EsSearch;
+}) => FieldValuesQuery;
+
+const valueLimit = 100;
+
+/**
+ * valueLookupField resolves the field a terms aggregation can run on, or
+ * undefined when none can. A text field is analyzed, so its own doc values are
+ * absent and the aggregation goes through the keyword sibling _field_caps
+ * reports beside it. Dates are excluded deliberately: every timestamp is
+ * distinct, so a value list says nothing the date-math presets do not.
+ */
+export function valueLookupField(
+ fields: EsFieldMapping[],
+ name: string | undefined,
+): string | undefined {
+ if (!name) return undefined;
+ const field = fields.find((entry) => entry.name === name);
+ if (!field || fieldFamily(field) === "date") return undefined;
+ if (field.aggregatable !== false) return field.name;
+ const keyword = fields.find(
+ (entry) => entry.name === `${name}.keyword` && entry.aggregatable !== false,
+ );
+ return keyword?.name;
+}
+
+type ValuesRequestBody = {
+ index: string;
+ field: string;
+ q?: string;
+ limit?: number;
+ search?: EsSearch;
+ params?: Record;
+ roles?: Record;
+};
+
+async function postValues(
+ baseUrl: string,
+ body: ValuesRequestBody,
+): Promise {
+ const response = await fetch(`${baseUrl}/values`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(body),
+ });
+ if (!response.ok) {
+ const text = (await response.text()).trim();
+ const error = new Error(text || `value lookup failed: ${response.status}`);
+ (error as Error & { status?: number }).status = response.status;
+ throw error;
+ }
+ return (await response.json()) as FieldValuesResult;
+}
+
+/**
+ * makeFieldValueLookup binds a lookup to a connection and an index. A scope the
+ * server cannot compile — a sibling condition left half-finished — is answered
+ * across the whole index instead, and the result says so, so the widened scope
+ * is visible rather than silently assumed. The scope is compiled server-side
+ * against `params`, so a sibling condition that interpolates `{{.params.…}}`
+ * narrows the suggestions the same way a run would.
+ */
+export function makeFieldValueLookup(options: {
+ baseUrl: string;
+ index: string;
+ params?: Record;
+ roles?: Record;
+}): FieldValuesSource | undefined {
+ const { baseUrl, index, params, roles } = options;
+ if (!baseUrl || !index) return undefined;
+ return ({ field, search }) => ({
+ key: JSON.stringify([
+ baseUrl,
+ index,
+ field,
+ search ?? null,
+ params ?? null,
+ roles ?? null,
+ ]),
+ fetch: async (query) => {
+ const body: ValuesRequestBody = {
+ index,
+ field,
+ q: query,
+ limit: valueLimit,
+ ...(search ? { search } : {}),
+ ...(params && Object.keys(params).length ? { params } : {}),
+ ...(roles && Object.keys(roles).length ? { roles } : {}),
+ };
+ try {
+ return await postValues(baseUrl, body);
+ } catch (error) {
+ const status = (error as Error & { status?: number }).status;
+ if (!search || status !== 422) throw error;
+ const { search: _dropped, ...unscoped } = body;
+ return postValues(baseUrl, unscoped);
+ }
+ },
+ });
+}
diff --git a/packages/ui/src/profiles/esParamMappingModel.test.ts b/packages/ui/src/profiles/esParamMappingModel.test.ts
new file mode 100644
index 00000000..1af0940c
--- /dev/null
+++ b/packages/ui/src/profiles/esParamMappingModel.test.ts
@@ -0,0 +1,307 @@
+import { describe, expect, it } from "vitest";
+import type { EsSearch } from "./esQueryBuilderModel";
+import {
+ addParamMapping,
+ bindParamOperand,
+ paramMappings,
+ reconcileParamMappings,
+ reconcileSearchParamMappings,
+ removeParamMapping,
+} from "./esParamMappingModel";
+import type { ParamDraft } from "./profileWizardModel";
+
+const filterParams: ParamDraft[] = [
+ { name: "service", type: "string", role: "filter" },
+ { name: "schemes", type: "list", role: "filter" },
+];
+
+describe("parameter query mappings", () => {
+ it("adds more than one scalar condition for the same parameter", () => {
+ const first = addParamMapping({
+ search: {},
+ params: filterParams,
+ name: "service",
+ field: "service.name",
+ });
+ const second = addParamMapping({
+ ...first,
+ name: "service",
+ field: "peer.service",
+ });
+
+ expect(second).toEqual({
+ search: {
+ query: {
+ op: "bool",
+ conditions: [
+ {
+ op: "term",
+ occur: "filter",
+ field: "service.name",
+ value: { param: "service" },
+ optional: true,
+ },
+ {
+ op: "term",
+ occur: "filter",
+ field: "peer.service",
+ value: { param: "service" },
+ optional: true,
+ },
+ ],
+ },
+ },
+ params: filterParams,
+ });
+ expect(paramMappings(second.search, "service")).toEqual([
+ { path: [0], field: "service.name", operand: "value" },
+ { path: [1], field: "peer.service", operand: "value" },
+ ]);
+ });
+
+ it("moves a list mapping and keeps its native field linked", () => {
+ const existing: EsSearch = {
+ query: {
+ op: "bool",
+ conditions: [
+ {
+ op: "terms",
+ field: "old.scheme",
+ values: ["literal", { param: "schemes" }],
+ },
+ ],
+ },
+ };
+
+ const result = addParamMapping({
+ search: existing,
+ params: filterParams,
+ name: "schemes",
+ field: "scheme.id",
+ });
+
+ expect(result.search.query?.conditions).toEqual([
+ { op: "terms", field: "old.scheme", values: ["literal"] },
+ {
+ op: "terms",
+ occur: "filter",
+ field: "scheme.id",
+ value: { param: "schemes" },
+ optional: true,
+ },
+ ]);
+ expect(result.params[1].field).toBe("scheme.id");
+ expect(paramMappings(result.search, "schemes")).toEqual([
+ { path: [1], field: "scheme.id", operand: "value" },
+ ]);
+ });
+
+ it("removes only the selected reference and prunes an empty leaf", () => {
+ const search: EsSearch = {
+ query: {
+ op: "bool",
+ conditions: [
+ {
+ op: "terms",
+ field: "scheme.id",
+ values: ["literal", { param: "schemes" }],
+ },
+ { op: "term", field: "service.name", value: { param: "service" } },
+ ],
+ },
+ };
+
+ const list = removeParamMapping({
+ search,
+ params: filterParams,
+ name: "schemes",
+ path: [0],
+ });
+ expect(list.search.query?.conditions).toEqual([
+ { op: "terms", field: "scheme.id", values: ["literal"] },
+ { op: "term", field: "service.name", value: { param: "service" } },
+ ]);
+ expect(list.params[1].field).toBeUndefined();
+
+ const scalar = removeParamMapping({
+ ...list,
+ name: "service",
+ path: [1],
+ });
+ expect(scalar.search.query?.conditions).toEqual([
+ { op: "terms", field: "scheme.id", values: ["literal"] },
+ ]);
+ });
+
+ it("binds a multiple operand canonically without a stale singular value", () => {
+ const result = bindParamOperand({
+ search: {
+ query: {
+ op: "terms",
+ field: "scheme.id",
+ value: "stale",
+ values: ["literal"],
+ },
+ },
+ params: filterParams,
+ path: [],
+ operand: "values",
+ name: "schemes",
+ });
+
+ expect(result.search.query).toEqual({
+ op: "terms",
+ field: "scheme.id",
+ value: undefined,
+ values: [{ param: "schemes" }],
+ gt: undefined,
+ gte: undefined,
+ lt: undefined,
+ lte: undefined,
+ conditions: undefined,
+ });
+ expect(result.params[1].field).toBe("scheme.id");
+ });
+
+ it("keeps a linked list field synchronized across query tree edits", () => {
+ const previousSearch: EsSearch = {
+ query: {
+ op: "bool",
+ conditions: [
+ {
+ op: "terms",
+ field: "scheme.id",
+ value: { param: "schemes" },
+ },
+ ],
+ },
+ };
+ const params = [
+ filterParams[0],
+ { ...filterParams[1], field: "scheme.id" },
+ ];
+
+ const moved = reconcileSearchParamMappings({
+ previousSearch,
+ nextSearch: {
+ query: {
+ op: "bool",
+ conditions: [
+ {
+ op: "terms",
+ field: "scheme.code",
+ value: { param: "schemes" },
+ },
+ ],
+ },
+ },
+ params,
+ });
+ expect(moved.params[1].field).toBe("scheme.code");
+
+ const removed = reconcileSearchParamMappings({
+ previousSearch: moved.search,
+ nextSearch: { query: { op: "bool", conditions: [] } },
+ params: moved.params,
+ });
+ expect(removed.params[1].field).toBeUndefined();
+ });
+
+ it("preserves a native-only list field across unrelated query edits", () => {
+ const params = [
+ filterParams[0],
+ { ...filterParams[1], field: "legacy.scheme" },
+ ];
+
+ const edit = reconcileSearchParamMappings({
+ previousSearch: {},
+ nextSearch: {
+ query: { op: "term", field: "service.name", value: "payments" },
+ },
+ params,
+ });
+
+ expect(edit.params[1].field).toBe("legacy.scheme");
+ });
+
+ it("maps time roles and rejects automatic paging roles", () => {
+ const time = addParamMapping({
+ search: {},
+ params: [{ name: "from", type: "date", role: "time-from" }],
+ name: "from",
+ field: "startTimeMillis",
+ });
+ expect(time.search.timeField).toBe("startTimeMillis");
+
+ expect(() =>
+ addParamMapping({
+ search: {},
+ params: [{ name: "limit", type: "number", role: "limit" }],
+ name: "limit",
+ field: "size",
+ }),
+ ).toThrow("limit parameter limit cannot map to a query field");
+ });
+});
+
+describe("parameter definition reconciliation", () => {
+ it("renames every operand and gate atomically", () => {
+ const search: EsSearch = {
+ query: {
+ op: "bool",
+ conditions: [
+ { op: "term", field: "service.name", value: { param: "service" } },
+ { op: "exists", field: "error", when: "service" },
+ ],
+ },
+ };
+ const next = [{ ...filterParams[0], name: "application" }, filterParams[1]];
+
+ expect(
+ reconcileParamMappings({ search, previous: filterParams, next }),
+ ).toEqual({
+ search: {
+ query: {
+ op: "bool",
+ conditions: [
+ {
+ op: "term",
+ field: "service.name",
+ value: { param: "application" },
+ },
+ { op: "exists", field: "error", when: "application" },
+ ],
+ },
+ },
+ params: next,
+ });
+ });
+
+ it("removes deleted references and preserves unrelated conditions", () => {
+ const search: EsSearch = {
+ query: {
+ op: "bool",
+ conditions: [
+ { op: "term", field: "service.name", value: { param: "service" } },
+ { op: "term", field: "level", value: "error" },
+ ],
+ },
+ };
+
+ expect(
+ reconcileParamMappings({
+ search,
+ previous: filterParams,
+ next: [filterParams[1]],
+ }),
+ ).toEqual({
+ search: {
+ query: {
+ op: "bool",
+ conditions: [{ op: "term", field: "level", value: "error" }],
+ },
+ },
+ params: [filterParams[1]],
+ });
+ });
+});
diff --git a/packages/ui/src/profiles/esParamMappingModel.ts b/packages/ui/src/profiles/esParamMappingModel.ts
new file mode 100644
index 00000000..74f7dffa
--- /dev/null
+++ b/packages/ui/src/profiles/esParamMappingModel.ts
@@ -0,0 +1,410 @@
+import type {
+ ConditionPath,
+ EsCondition,
+ EsSearch,
+ EsValue,
+} from "./esQueryBuilderModel";
+import {
+ conditionAt,
+ emptyGroup,
+ isParamValue,
+ updateAt,
+} from "./esQueryBuilderModel";
+import { conditionOperandPatch } from "./esQueryOperandModel";
+import { applyPatch, type ParamDraft } from "./profileWizardModel";
+
+export type ParamOperand = "value" | "values" | "gt" | "gte" | "lt" | "lte";
+
+export type ParamMapping = {
+ path: ConditionPath;
+ field: string;
+ operand: ParamOperand;
+};
+
+export type ParamMappingEdit = {
+ search: EsSearch;
+ params: ParamDraft[];
+};
+
+export function paramMappings(
+ search: EsSearch | undefined,
+ name: string,
+): ParamMapping[] {
+ const found: ParamMapping[] = [];
+ const walk = (condition: EsCondition | undefined, path: ConditionPath) => {
+ if (!condition) return;
+ for (const operand of operands) {
+ const value = condition[operand];
+ const values = Array.isArray(value) ? value : [value];
+ if (
+ condition.field &&
+ values.some((entry) => isParamValue(entry) && entry.param === name)
+ ) {
+ found.push({ path, field: condition.field, operand });
+ }
+ }
+ condition.conditions?.forEach((child, index) =>
+ walk(child, [...path, index]),
+ );
+ };
+ walk(search?.query, []);
+ return found;
+}
+
+export function addParamMapping({
+ search,
+ params,
+ name,
+ field,
+}: ParamMappingEdit & { name: string; field: string }): ParamMappingEdit {
+ const param = namedParam(params, name);
+ if (param.role === "limit" || param.role === "offset") {
+ throw new Error(
+ `${param.role} parameter ${name} cannot map to a query field`,
+ );
+ }
+ if (param.role === "time-from" || param.role === "time-to") {
+ return { search: { ...search, timeField: field }, params };
+ }
+ const withoutPrevious =
+ param.type === "list" ? stripParamReferences(search, name) : search;
+ const condition: EsCondition = {
+ op: param.type === "list" ? "terms" : "term",
+ occur: "filter",
+ field,
+ value: { param: name },
+ ...(!param.required ? { optional: true } : {}),
+ };
+ return {
+ search: appendCondition(withoutPrevious, condition),
+ params: syncNativeField(
+ params,
+ name,
+ param.type === "list" ? field : undefined,
+ ),
+ };
+}
+
+export function bindParamOperand({
+ search,
+ params,
+ path,
+ operand,
+ name,
+}: ParamMappingEdit & {
+ path: ConditionPath;
+ operand: ParamOperand;
+ name: string;
+}): ParamMappingEdit {
+ const param = namedParam(params, name);
+ if (param.role && param.role !== "filter") {
+ throw new Error(
+ `${param.role} parameter ${name} cannot bind a query operand`,
+ );
+ }
+ const condition = search.query && conditionAt(search.query, path);
+ if (!condition?.field)
+ throw new Error(`condition for parameter ${name} has no field`);
+ const value = { param: name };
+ const patch =
+ operand === "values"
+ ? conditionOperandPatch({ arity: "multiple", values: [value] })
+ : operand === "value"
+ ? conditionOperandPatch({ arity: "single", value })
+ : conditionOperandPatch({ arity: "range", bound: operand, value });
+ const query = updateAt(search.query as EsCondition, path, (current) =>
+ applyPatch(current, patch),
+ );
+ const bound = { ...search, query };
+ return {
+ search:
+ param.type === "list" ? stripParamReferences(bound, name, path) : bound,
+ params: syncNativeField(
+ params,
+ name,
+ param.type === "list" ? condition.field : undefined,
+ ),
+ };
+}
+
+export function removeParamMapping({
+ search,
+ params,
+ name,
+ path,
+}: ParamMappingEdit & {
+ name: string;
+ path?: ConditionPath;
+}): ParamMappingEdit {
+ const param = namedParam(params, name);
+ if (param.role === "time-from" || param.role === "time-to") {
+ const next = { ...search };
+ delete next.timeField;
+ return { search: next, params };
+ }
+ if (!path) {
+ if (param.type !== "list")
+ throw new Error(`parameter ${name} has no field mapping to remove`);
+ return { search, params: syncNativeField(params, name, undefined) };
+ }
+ const query = search.query
+ ? editAt(search.query, path, (condition) =>
+ removeReference(condition, name),
+ )
+ : undefined;
+ return {
+ search: { ...search, query: query ?? emptyGroup() },
+ params: syncNativeField(params, name, undefined),
+ };
+}
+
+export function reconcileParamMappings({
+ search,
+ previous,
+ next,
+}: {
+ search: EsSearch;
+ previous: ParamDraft[];
+ next: ParamDraft[];
+}): ParamMappingEdit {
+ let reconciled = search;
+ const previousNames = new Set(
+ previous.map((param) => param.name).filter(Boolean),
+ );
+ const nextNames = new Set(next.map((param) => param.name).filter(Boolean));
+ const renamed = new Set();
+ if (previous.length === next.length) {
+ previous.forEach((param, index) => {
+ const oldName = param.name;
+ const newName = next[index]?.name;
+ if (
+ oldName &&
+ newName &&
+ oldName !== newName &&
+ !nextNames.has(oldName) &&
+ !previousNames.has(newName)
+ ) {
+ reconciled = renameParamReferences(reconciled, oldName, newName);
+ renamed.add(oldName);
+ }
+ });
+ }
+ for (const param of previous) {
+ if (param.name && !renamed.has(param.name) && !nextNames.has(param.name)) {
+ reconciled = stripParamReferences(reconciled, param.name);
+ }
+ }
+ return {
+ search: reconciled,
+ params: syncAllNativeFields(reconciled, next, search),
+ };
+}
+
+export function reconcileSearchParamMappings({
+ previousSearch,
+ nextSearch,
+ params,
+}: {
+ previousSearch: EsSearch;
+ nextSearch: EsSearch;
+ params: ParamDraft[];
+}): ParamMappingEdit {
+ return {
+ search: nextSearch,
+ params: syncAllNativeFields(nextSearch, params, previousSearch),
+ };
+}
+
+const operands: ParamOperand[] = ["value", "values", "gt", "gte", "lt", "lte"];
+
+function namedParam(params: ParamDraft[], name: string): ParamDraft {
+ const param = params.find((candidate) => candidate.name === name);
+ if (!param) throw new Error(`parameter ${name} does not exist`);
+ return param;
+}
+
+function appendCondition(search: EsSearch, condition: EsCondition): EsSearch {
+ if (!search.query || search.query.op === "match_all") {
+ return { ...search, query: { ...emptyGroup(), conditions: [condition] } };
+ }
+ if (search.query.op === "bool") {
+ return {
+ ...search,
+ query: {
+ ...search.query,
+ conditions: [...(search.query.conditions ?? []), condition],
+ },
+ };
+ }
+ return {
+ ...search,
+ query: { ...emptyGroup(), conditions: [search.query, condition] },
+ };
+}
+
+function stripParamReferences(
+ search: EsSearch,
+ name: string,
+ keepPath?: ConditionPath,
+): EsSearch {
+ const query = stripCondition(search.query, name, [], keepPath);
+ return { ...search, query: query ?? emptyGroup() };
+}
+
+function stripCondition(
+ condition: EsCondition | undefined,
+ name: string,
+ path: ConditionPath,
+ keepPath?: ConditionPath,
+): EsCondition | undefined {
+ if (!condition) return undefined;
+ if (keepPath && samePath(path, keepPath)) return condition;
+ if (condition.when === name) return undefined;
+ let next = removeReference(condition, name);
+ if (!next) return undefined;
+ if (next.conditions) {
+ const conditions = next.conditions.flatMap((child, index) => {
+ const stripped = stripCondition(child, name, [...path, index], keepPath);
+ return stripped ? [stripped] : [];
+ });
+ next = { ...next, conditions };
+ if (conditions.length === 0 && (condition.conditions?.length ?? 0) > 0)
+ return undefined;
+ }
+ return next;
+}
+
+function removeReference(
+ condition: EsCondition,
+ name: string,
+): EsCondition | undefined {
+ let removed = false;
+ const next = { ...condition };
+ for (const operand of operands) {
+ const value = condition[operand];
+ if (operand === "values") {
+ const values = (condition.values ?? []).filter((entry) => {
+ const matches = isParamValue(entry) && entry.param === name;
+ removed ||= matches;
+ return !matches;
+ });
+ // Deleted rather than set to undefined: the search is serialized, and a
+ // present `values: undefined` is a key the backend has to interpret.
+ if (values.length) next.values = values;
+ else delete next.values;
+ } else if (isParamValue(value) && value.param === name) {
+ delete next[operand];
+ removed = true;
+ }
+ }
+ return removed && !hasOperand(next) ? undefined : next;
+}
+
+function hasOperand(condition: EsCondition): boolean {
+ return (
+ condition.value !== undefined ||
+ Boolean(condition.values?.length) ||
+ condition.gt !== undefined ||
+ condition.gte !== undefined ||
+ condition.lt !== undefined ||
+ condition.lte !== undefined ||
+ Boolean(condition.conditions?.length)
+ );
+}
+
+function editAt(
+ condition: EsCondition,
+ path: ConditionPath,
+ edit: (condition: EsCondition) => EsCondition | undefined,
+): EsCondition | undefined {
+ if (path.length === 0) return edit(condition);
+ const [target, ...rest] = path;
+ const children = condition.conditions ?? [];
+ const child = target === undefined ? undefined : children[target];
+ if (!child) throw new Error(`condition path ${path.join(".")} does not exist`);
+ const edited = editAt(child, rest, edit);
+ return {
+ ...condition,
+ conditions: children.flatMap((child, index) =>
+ index !== target ? [child] : edited ? [edited] : [],
+ ),
+ };
+}
+
+function renameParamReferences(
+ search: EsSearch,
+ oldName: string,
+ newName: string,
+): EsSearch {
+ const rename = (condition: EsCondition): EsCondition => {
+ const next = { ...condition };
+ for (const operand of operands) {
+ const value = condition[operand];
+ if (operand === "values") {
+ if (condition.values) {
+ next.values = condition.values.map((entry) =>
+ renamedValue(entry, oldName, newName),
+ );
+ }
+ } else {
+ next[operand] = renamedValue(value, oldName, newName) as never;
+ }
+ }
+ if (condition.when === oldName) next.when = newName;
+ if (condition.conditions)
+ next.conditions = condition.conditions.map(rename);
+ return next;
+ };
+ if (!search.query) return { ...search };
+ return { ...search, query: rename(search.query) };
+}
+
+function renamedValue(
+ value: EsValue,
+ oldName: string,
+ newName: string,
+): EsValue {
+ return isParamValue(value) && value.param === oldName
+ ? { param: newName }
+ : value;
+}
+
+function syncNativeField(
+ params: ParamDraft[],
+ name: string,
+ field: string | undefined,
+): ParamDraft[] {
+ const param = namedParam(params, name);
+ if (param.type !== "list") return params;
+ return params.map((candidate) => {
+ if (candidate.name !== name) return candidate;
+ const next: ParamDraft = { ...candidate, ...(field ? { field } : {}) };
+ if (!field) delete next.field;
+ return next;
+ });
+}
+
+function syncAllNativeFields(
+ search: EsSearch,
+ params: ParamDraft[],
+ previousSearch: EsSearch,
+): ParamDraft[] {
+ return params.map((param) => {
+ if (param.type !== "list" || !param.name) return param;
+ const mapping = paramMappings(search, param.name)[0];
+ const wasMapped = paramMappings(previousSearch, param.name).length > 0;
+ if (!mapping && !wasMapped) return param;
+ const field = mapping?.field;
+ if (field === param.field) return param;
+ const next: ParamDraft = { ...param, ...(field ? { field } : {}) };
+ if (!field) delete next.field;
+ return next;
+ });
+}
+
+function samePath(left: ConditionPath, right: ConditionPath): boolean {
+ return (
+ left.length === right.length &&
+ left.every((value, index) => value === right[index])
+ );
+}
diff --git a/packages/ui/src/profiles/esParamMappingPill.tsx b/packages/ui/src/profiles/esParamMappingPill.tsx
new file mode 100644
index 00000000..7300e824
--- /dev/null
+++ b/packages/ui/src/profiles/esParamMappingPill.tsx
@@ -0,0 +1,32 @@
+/**
+ * The chip showing which parameter an operand is bound to.
+ *
+ * Split from esParamOperandExtension.tsx: that module exports the operand
+ * extension, which is not a component, and a module may not export both
+ * (react/only-export-components).
+ */
+
+
+export function ParamMappingPill({
+ name,
+ label,
+ onClear
+}: {
+ name: string;
+ label: string;
+ onClear: () => void;
+}) {
+ return (
+
+ {name}
+
+ ×
+
+
+ );
+}
diff --git a/packages/ui/src/profiles/esParamOperandExtension.tsx b/packages/ui/src/profiles/esParamOperandExtension.tsx
new file mode 100644
index 00000000..6a5f6287
--- /dev/null
+++ b/packages/ui/src/profiles/esParamOperandExtension.tsx
@@ -0,0 +1,83 @@
+import { ParamMappingPill } from "./esParamMappingPill";
+import { applyPostExtensions } from "../components/json-schema-form-extensions";
+import type { FieldControl, PostExtension } from "../components/json-schema-form-types";
+import { Select } from "../components/select";
+import type { ReactNode } from "react";
+import { isParamValue, type EsValue } from "./esQueryBuilderModel";
+import type { ParamDraft } from "./profileWizardModel";
+
+const esParamOperandPost: PostExtension = (field, nodes, ctx) => {
+ if (field.schema["x-clicky-component"] !== "es-query-operand") return nodes;
+ const label = String(field.schema["x-es-operand-label"] ?? field.label);
+ const params = operandParams((ctx?.rootValue?.params ?? []) as ParamDraft[]);
+ const bound = boundParam(field.value);
+ const selector = params.length ? (
+
+ ({ value: param, label: param }))}
+ onChange={(event) => {
+ if (event.target.value) field.onChange({ param: event.target.value });
+ }}
+ />
+
+ ) : null;
+ return {
+ label: nodes.label,
+ value: bound ? (
+
+ {Array.isArray(field.value) ? nodes.value : null}
+ field.onChange(undefined)}
+ />
+
+ ) : (
+
+ {nodes.value}
+ {selector}
+
+ ),
+ };
+};
+
+export function extendEsParamOperand(input: {
+ label: string;
+ value: EsValue | EsValue[];
+ onChange: (next: unknown) => void;
+ node: ReactNode;
+ params: ParamDraft[];
+}): ReactNode {
+ const field: FieldControl = {
+ key: "operand",
+ kind: Array.isArray(input.value) ? "array" : "string",
+ label: input.label,
+ required: false,
+ schema: {
+ "x-clicky-component": "es-query-operand",
+ "x-es-operand-label": input.label,
+ },
+ value: input.value,
+ onChange: input.onChange,
+ };
+ return applyPostExtensions(
+ field,
+ { label: null, value: input.node },
+ [esParamOperandPost],
+ { rootValue: { params: input.params } },
+ ).value;
+}
+
+function operandParams(params: ParamDraft[]): string[] {
+ return params.flatMap((param) =>
+ param.name && (!param.role || param.role === "filter") ? [param.name] : [],
+ );
+}
+
+function boundParam(value: EsValue | EsValue[]): string | undefined {
+ const values = Array.isArray(value) ? value : [value];
+ return values.find(isParamValue)?.param;
+}
diff --git a/packages/ui/src/profiles/esQueryBuilder.test.tsx b/packages/ui/src/profiles/esQueryBuilder.test.tsx
new file mode 100644
index 00000000..29dc1d7f
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryBuilder.test.tsx
@@ -0,0 +1,349 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+import { EsQueryBuilder } from "./esQueryBuilder";
+import { esQueryBuilderFormExtensions } from "./esQueryBuilderExtension";
+import { defaultParamValues, esQueryFields, paramNames, paramRoles } from "./esQueryBuilderForm";
+import { compileRequestBody, type EsCompileRequest } from "./esQueryCompile";
+import type { EsSearch } from "./esQueryBuilderModel";
+
+// useCompiledSearch only issues its request once effects run, which server
+// rendering never does — so the wiring is asserted on what the hook was handed.
+const compileInputs = vi.hoisted(() => [] as EsCompileRequest[]);
+vi.mock("./esQueryCompile", async (importOriginal) => {
+ const original = await importOriginal();
+ return {
+ ...original,
+ useCompiledSearch: (input: EsCompileRequest) => {
+ compileInputs.push(input);
+ return original.useCompiledSearch(input);
+ },
+ };
+});
+import type {
+ EsBuilderVocabulary,
+ EsFieldMapping,
+ EsOperatorInfo,
+} from "./esQueryOperators";
+
+const operator = (
+ op: string,
+ fieldTypes: string[],
+ extra: Partial = {},
+): EsOperatorInfo => ({
+ op,
+ label: op,
+ arity: "single",
+ needsField: true,
+ fieldTypes,
+ ...extra,
+});
+
+const vocabulary: EsBuilderVocabulary = {
+ catalog: [
+ operator("term", ["keyword", "number", "boolean", "ip", "date"]),
+ operator("terms", ["keyword", "number", "boolean", "ip", "date"], {
+ arity: "multiple",
+ }),
+ operator("range", ["date", "number", "ip"], { arity: "range" }),
+ operator("exists", ["any"], { arity: "none" }),
+ operator("bool", [], {
+ op: "bool",
+ label: "group",
+ arity: "group",
+ group: true,
+ needsField: false,
+ }),
+ ],
+ occurs: ["filter", "must", "should", "must_not"],
+ qualifierNames: ["boost"],
+ qualifiers: { boost: { type: "number", title: "Boost" } },
+ sortOrders: ["asc", "desc"],
+};
+
+const fields: EsFieldMapping[] = [
+ { name: "@timestamp", dataType: "date", aggregatable: true },
+ { name: "service.name", dataType: "keyword", aggregatable: true },
+ { name: "message", dataType: "text", aggregatable: false },
+];
+
+const render = (search: EsSearch, extra: Record = {}) =>
+ renderToStaticMarkup(
+ {}}
+ fields={fields}
+ vocabulary={vocabulary}
+ {...extra}
+ />,
+ );
+
+describe("EsQueryBuilder", () => {
+ it("renders the root group without a clause or remove control", () => {
+ const html = render({});
+ expect(html).toContain('data-es-group="bool"');
+ expect(html).not.toContain('aria-label="Clause"');
+ expect(html).not.toContain('aria-label="Remove group"');
+ });
+
+ it("renders one condition row per child of the root group", () => {
+ const html = render({
+ query: {
+ op: "bool",
+ conditions: [
+ { op: "term", field: "service.name" },
+ { op: "exists", field: "message" },
+ ],
+ },
+ });
+ expect(html.match(/aria-label="Operator"/g)).toHaveLength(2);
+ });
+
+ it("offers only date fields as the time field", () => {
+ const html = render({ timeField: "@timestamp" });
+ const at = html.indexOf('aria-label="Time field"');
+ expect(at).toBeGreaterThan(-1);
+ // Combobox keeps its options closed, so the selected value is what SSR shows.
+ expect(html.slice(at, html.indexOf(">", at))).toContain('value="@timestamp"');
+ });
+
+ it("renders the sort and output editors", () => {
+ const html = render({ sort: [{ field: "@timestamp", order: "desc" }] });
+ expect(html).toContain('aria-label="Sort field"');
+ expect(html).toContain('aria-label="From"');
+ });
+
+ it("shows the compiled preview only when a compilation is supplied", () => {
+ expect(render({})).not.toContain("Compiled DSL");
+ expect(
+ render({}, {
+ compilation: { query: '{"query":{"match_all":{}}}', loading: false },
+ }),
+ ).toContain("Compiled DSL");
+ });
+
+ // Raw DSL is the other tab, not a button inside this one: the builder edits a
+ // specification and knows nothing about where the host stores the alternative.
+ it("keeps the mode switch out of the builder", () => {
+ expect(render({})).not.toContain("Edit raw DSL");
+ });
+});
+
+describe("EsQueryBuilder value lookups", () => {
+ // An analyzed text field has no doc values of its own, so its keyword sibling
+ // is what a value list can be aggregated from.
+ const lookupFields: EsFieldMapping[] = [
+ ...fields,
+ { name: "message.keyword", dataType: "keyword", aggregatable: true },
+ ];
+
+ const twoConditions: EsSearch = {
+ query: {
+ op: "bool",
+ conditions: [
+ { op: "term", field: "service.name", value: "pay" },
+ { op: "term", field: "message", value: "timeout" },
+ ],
+ },
+ };
+
+ const renderWithLookup = (search: EsSearch) => {
+ const asked: { field: string; search?: EsSearch }[] = [];
+ const values = (request: { field: string; search?: EsSearch }) => {
+ asked.push(request);
+ return { key: request.field, fetch: async () => ({ values: [], total: 0, scoped: true }) };
+ };
+ const html = renderToStaticMarkup(
+
+ {}}
+ fields={lookupFields}
+ vocabulary={vocabulary}
+ values={values}
+ />
+ ,
+ );
+ return { asked, html };
+ };
+
+ // The row being edited holds the value the list is meant to complete, so
+ // scoping by it would filter the suggestions down to what was already typed.
+ it("scopes a row's lookup to the query without that row", () => {
+ const { asked } = renderWithLookup(twoConditions);
+ expect(asked.map((entry) => entry.field)).toEqual([
+ "service.name",
+ "message.keyword",
+ ]);
+ expect(asked[0]?.search?.query?.conditions).toEqual([
+ { op: "term", field: "message", value: "timeout" },
+ ]);
+ expect(asked[1]?.search?.query?.conditions).toEqual([
+ { op: "term", field: "service.name", value: "pay" },
+ ]);
+ });
+
+ it("asks for no lookup on a field that cannot be aggregated", () => {
+ const { asked } = renderWithLookup({
+ query: { op: "bool", conditions: [{ op: "term", field: "@timestamp" }] },
+ });
+ expect(asked).toEqual([]);
+ });
+
+ it("picks the operand from the field's values when a lookup exists", () => {
+ const { html } = renderWithLookup({
+ query: { op: "bool", conditions: [{ op: "term", field: "service.name" }] },
+ });
+ expect(html).toMatch(/role="combobox"[^>]*aria-label="Value"/);
+ });
+
+ it("picks multiple operands from existing values for is one of", () => {
+ const { html } = renderWithLookup({
+ query: {
+ op: "bool",
+ conditions: [{ op: "terms", field: "service.name", values: ["payments"] }],
+ },
+ });
+ expect(html).toMatch(/role="combobox"[^>]*aria-label="Values"/);
+ });
+
+ it("leaves the operand a plain input when the host has no connection", () => {
+ const html = render({
+ query: { op: "bool", conditions: [{ op: "term", field: "service.name" }] },
+ });
+ expect(html).toContain('aria-label="Value"');
+ expect(html).not.toMatch(/role="combobox"[^>]*aria-label="Value"/);
+ });
+});
+
+describe("esQueryBuilderFormExtensions", () => {
+ const [post] = esQueryBuilderFormExtensions.post;
+ const nodes = { label: "label", value: "input" };
+ const field = (component: string | undefined) => ({
+ key: "search",
+ kind: "object" as const,
+ label: "Search",
+ required: false,
+ schema: component ? { "x-clicky-component": component } : {},
+ value: {},
+ onChange: () => {},
+ });
+
+ it("passes the rendered nodes through for any other component", () => {
+ expect(post(field("profile-query-builder"), nodes)).toBe(nodes);
+ expect(post(field(undefined), nodes)).toBe(nodes);
+ });
+
+ it("replaces the value node for the es-query-builder component", () => {
+ const replaced = post(field("es-query-builder"), nodes);
+ expect(replaced.label).toBe(nodes.label);
+ expect(replaced.value).not.toBe(nodes.value);
+ });
+});
+
+describe("param plumbing", () => {
+ it("lists declared parameter names in order, skipping unnamed drafts", () => {
+ expect(
+ paramNames([{ name: "env" }, {}, { name: "" }, { name: "since" }]),
+ ).toEqual(["env", "since"]);
+ });
+
+ it("maps only the parameters that carry a role", () => {
+ expect(
+ paramRoles([
+ { name: "since", role: "time-from" },
+ { name: "env" },
+ { name: "rows", role: "limit" },
+ ]),
+ ).toEqual({ since: "time-from", rows: "limit" });
+ });
+
+ it("takes the default of every named parameter that declares one", () => {
+ expect(
+ defaultParamValues([
+ { name: "country", default: "kenya" },
+ { name: "env" },
+ { name: "rows", default: 500 },
+ { default: "orphan" },
+ ]),
+ ).toEqual({ country: "kenya", rows: 500 });
+ });
+
+ it("returns empty plumbing when the profile declares no parameters", () => {
+ expect(paramNames(undefined)).toEqual([]);
+ expect(paramRoles(undefined)).toEqual({});
+ expect(defaultParamValues(undefined)).toEqual({});
+ });
+});
+
+// The preview compiles server-side against the parameter values a run would
+// start with, so an operand that binds {param:…} or interpolates {{.params.…}}
+// resolves in the panel instead of showing template text.
+describe("EsQueryBuilderField compilation", () => {
+ const [post] = esQueryBuilderFormExtensions.post;
+
+ it("sends the declared parameter defaults and roles to /compile", () => {
+ compileInputs.length = 0;
+ renderToStaticMarkup(
+
+ {
+ post(
+ {
+ key: "search",
+ kind: "object" as const,
+ label: "Search",
+ required: false,
+ schema: { "x-clicky-component": "es-query-builder" },
+ value: {
+ query: {
+ op: "term",
+ field: "process.serviceName",
+ value: "{{.params.country}}-api",
+ },
+ },
+ onChange: () => {},
+ },
+ { label: "label", value: "input" },
+ {
+ rootValue: {
+ provider: {
+ connection: "connection://11111111-2222-3333-4444-555555555555",
+ options: { index: "jaeger-span*" },
+ },
+ params: [
+ { name: "country", default: "kenya" },
+ { name: "since", role: "time-from", default: "now-1h" },
+ { name: "env" },
+ ],
+ },
+ },
+ ).value as React.ReactNode
+ }
+ ,
+ );
+
+ expect(compileInputs).toHaveLength(1);
+ expect(compileInputs[0]?.params).toEqual({
+ country: "kenya",
+ since: "now-1h",
+ });
+ expect(compileInputs[0]?.roles).toEqual({ since: "time-from" });
+ expect(JSON.parse(compileRequestBody(compileInputs[0]!)).params).toEqual({
+ country: "kenya",
+ since: "now-1h",
+ });
+ });
+});
+
+describe("esQueryFields", () => {
+ it("reads the mappings off an OpenSearch field completion", () => {
+ expect(
+ esQueryFields({ kind: "json-fields", vocabulary: "opensearch", fields }),
+ ).toEqual(fields);
+ });
+
+ it("builds against free text for a completion of any other kind", () => {
+ expect(esQueryFields({ kind: "sql", dialect: "postgresql" })).toEqual([]);
+ expect(esQueryFields(undefined)).toEqual([]);
+ });
+});
diff --git a/packages/ui/src/profiles/esQueryBuilder.tsx b/packages/ui/src/profiles/esQueryBuilder.tsx
new file mode 100644
index 00000000..e649a33e
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryBuilder.tsx
@@ -0,0 +1,260 @@
+/**
+ * The query builder panel and the form extension that mounts it. The panel is
+ * pure: it takes a specification and the vocabulary the schema described, and
+ * reports edits. Everything that needs a connection — field mappings and the
+ * compiled preview — is wired by the host that has one.
+ */
+
+import { Combobox } from "../components/Combobox";
+import type { JsonSchemaProperty } from "../components/json-schema-form-types";
+import {
+ browserBaseUrl,
+ savedConnectionID,
+ useInspection
+} from "./connectionBrowserModel";
+import {
+ conditionAt,
+ emptyGroup,
+ insertAt,
+ removeAt,
+ updateAt,
+ type EsSearch
+} from "./esQueryBuilderModel";
+import {
+ makeFieldValueLookup,
+ valueLookupField,
+ type FieldValuesSource
+} from "./esFieldValues";
+import { EsQueryClauseGroup } from "./esQueryClauseGroup";
+import type {
+ EsQueryContext,
+ EsQueryTreeActions
+} from "./esQueryConditionRow";
+import {
+ esBuilderVocabulary,
+ fieldFamily,
+ type EsBuilderVocabulary,
+ type EsFieldMapping
+} from "./esQueryOperators";
+import { EsQueryOutputEditor } from "./esQueryOutputEditor";
+import {
+ EsQueryPreview
+ } from "./esQueryPreview";
+import { EsQuerySortEditor } from "./esQuerySortEditor";
+import type { ProfileDraft } from "./profileBuilderWorkspace";
+import type { ParamDraft } from "./profileWizardModel";
+import {
+ bindParamOperand,
+ reconcileSearchParamMappings,
+ removeParamMapping,
+ type ParamMappingEdit
+} from "./esParamMappingModel";
+import { defaultParamValues, esQueryFields, paramRoles } from "./esQueryBuilderForm";
+import { useCompiledSearch, type EsCompilation } from "./esQueryCompile";
+
+export type EsQueryBuilderProps = {
+ search: EsSearch;
+ onChange: (search: EsSearch) => void;
+ fields: EsFieldMapping[];
+ vocabulary: EsBuilderVocabulary;
+ /** Declared profile parameters an operand can bind to. */
+ params?: ParamDraft[];
+ onMappingChange?: (edit: ParamMappingEdit) => void;
+ /** Where a field's own values come from; absent without a connection. */
+ values?: FieldValuesSource;
+ compilation?: EsCompilation;
+ className?: string;
+};
+
+export function EsQueryBuilder({
+ search,
+ onChange,
+ fields,
+ vocabulary,
+ params = [],
+ onMappingChange,
+ values,
+ compilation,
+ className
+}: EsQueryBuilderProps) {
+ const root = search.query ?? emptyGroup();
+ const mappingFieldsChanged = (edit: ParamMappingEdit) =>
+ edit.params.some((param, index) => param.field !== params[index]?.field);
+ const commitMappingEdit = (edit: ParamMappingEdit) => {
+ if (onMappingChange) {
+ onMappingChange(edit);
+ return;
+ }
+ if (mappingFieldsChanged(edit)) {
+ throw new Error(
+ "list parameter mappings require an atomic mapping change handler",
+ );
+ }
+ onChange(edit.search);
+ };
+ const commitSearchEdit = (nextSearch: EsSearch) => {
+ const edit = reconcileSearchParamMappings({
+ previousSearch: search,
+ nextSearch,
+ params
+ });
+ if (mappingFieldsChanged(edit)) {
+ commitMappingEdit(edit);
+ return;
+ }
+ onChange(nextSearch);
+ };
+ const context: EsQueryContext = {
+ fields,
+ vocabulary,
+ params,
+ // The builder owns the tree, so it — not the host — decides what a lookup is
+ // scoped by: the query without the row being edited. Leaving that row in
+ // would filter the suggestions by the half-typed value they are meant to
+ // complete.
+ ...(values
+ ? {
+ values: ({ path, field }) => {
+ const target = valueLookupField(fields, field);
+ if (!target) return undefined;
+ return values({ field: target, search: { ...search, query: removeAt(root, path) } });
+ }
+ }
+ : {})
+ };
+ const actions: EsQueryTreeActions = {
+ update: (path, update) =>
+ commitSearchEdit({ ...search, query: updateAt(root, path, update) }),
+ insert: (groupPath, condition) =>
+ commitSearchEdit({
+ ...search,
+ query: insertAt(
+ root,
+ groupPath,
+ conditionAt(root, groupPath)?.conditions?.length ?? 0,
+ condition,
+ )
+ }),
+ remove: (path) =>
+ commitSearchEdit({ ...search, query: removeAt(root, path) }),
+ mapParam: (path, operand, name) => {
+ const edit = bindParamOperand({ search, params, path, operand, name });
+ commitMappingEdit(edit);
+ },
+ unmapParam: (path, name) => {
+ const edit = removeParamMapping({ search, params, name, path });
+ commitMappingEdit(edit);
+ }
+ };
+
+ return (
+
+
+
+ Time field
+ onChange({ ...search, timeField: next || undefined })}
+ options={fields
+ .filter((field) => fieldFamily(field) === "date")
+ .map((field) => ({ value: field.name, label: field.name }))}
+ placeholder="Date field…"
+ allowCustomValue
+ />
+
+ Where time-from and time-to parameters apply
+
+
+
onChange({ ...search, sort: sort.length ? sort : undefined })}
+ />
+ onChange({ ...search, ...patch })}
+ />
+ {compilation ? ) => void) | undefined;
+}) {
+ const connectionID = savedConnectionID(rootValue.provider?.connection);
+ const baseUrl = connectionID ? browserBaseUrl(connectionID) : "";
+ const target = String(rootValue.provider?.options?.index ?? "");
+ const inspection = useInspection({
+ cacheKey: "es-query-builder",
+ id: connectionID ?? "",
+ baseUrl,
+ enabled: baseUrl !== "",
+ database: "",
+ target
+ });
+ const roles = paramRoles(rootValue.params);
+ const params = defaultParamValues(rootValue.params);
+ const compilation = useCompiledSearch({
+ baseUrl,
+ search,
+ params,
+ roles,
+ enabled: baseUrl !== ""
+ });
+ const values = makeFieldValueLookup({ baseUrl, index: target, params, roles });
+
+ return (
+ onChange(next)}
+ fields={esQueryFields(inspection.completion)}
+ vocabulary={esBuilderVocabulary({ properties: { search: schema } })}
+ params={rootValue.params ?? []}
+ onMappingChange={(edit) => {
+ if (!onRootChange) {
+ throw new Error(
+ "query parameter mappings require an atomic root form update",
+ );
+ }
+ onRootChange({
+ ...rootValue,
+ params: edit.params,
+ provider: {
+ ...rootValue.provider,
+ options: {
+ ...rootValue.provider?.options,
+ search: edit.search
+ }
+ }
+ });
+ }}
+ {...(values ? { values } : {})}
+ compilation={compilation}
+ />
+ );
+}
diff --git a/packages/ui/src/profiles/esQueryBuilderExtension.tsx b/packages/ui/src/profiles/esQueryBuilderExtension.tsx
new file mode 100644
index 00000000..ac415a36
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryBuilderExtension.tsx
@@ -0,0 +1,30 @@
+/**
+ * The JSON-schema form extension that swaps in the OpenSearch query builder.
+ *
+ * It lives apart from esQueryBuilder.tsx because it is not a component, and a
+ * module that exports components must export nothing else for Fast Refresh to
+ * work (react/only-export-components).
+ */
+
+import type { PostExtension } from "../components/json-schema-form-types";
+import { EsQueryBuilderField } from "./esQueryBuilder";
+import type { EsSearch } from "./esQueryBuilderModel";
+import type { ProfileDraft } from "./profileBuilderWorkspace";
+
+const esQueryBuilderPost: PostExtension = (field, nodes, ctx) => {
+ if (field.schema["x-clicky-component"] !== "es-query-builder") return nodes;
+ return {
+ label: nodes.label,
+ value: (
+ {
+ const roles: Record = {};
+ for (const param of params ?? []) {
+ if (param.name && param.role) roles[param.name] = param.role;
+ }
+ return roles;
+}
+
+/**
+ * defaultParamValues is what the declared parameters resolve to before anyone
+ * filters. The compiler needs them to bind a {param:…} operand and to
+ * interpolate a {{.params.…}} one, so the preview shows the DSL a run produces.
+ */
+export function defaultParamValues(
+ params: ParamDraft[] | undefined,
+): Record {
+ return Object.fromEntries(
+ (params ?? [])
+ .filter((param) => param.name && param.default !== undefined)
+ .map((param) => [param.name as string, param.default]),
+ );
+}
+
+/**
+ * esQueryFields reads the field mappings off a browser inspection. Only an
+ * OpenSearch target carries them, so anything else builds against free text.
+ */
+export function esQueryFields(completion: unknown): EsFieldMapping[] {
+ const typed = completion as { kind?: string; fields?: EsFieldMapping[] };
+ return typed?.kind === "json-fields" ? (typed.fields ?? []) : [];
+}
diff --git a/packages/ui/src/profiles/esQueryBuilderModel.test.ts b/packages/ui/src/profiles/esQueryBuilderModel.test.ts
new file mode 100644
index 00000000..f75e1c3f
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryBuilderModel.test.ts
@@ -0,0 +1,180 @@
+import { describe, expect, it } from "vitest";
+import {
+ conditionAt,
+ emptyCondition,
+ fieldForParam,
+ insertAt,
+ isEmptySpec,
+ isParamValue,
+ normalizeOccur,
+ removeAt,
+ toBuilderMode,
+ toRawMode,
+ updateAt,
+ type EsCondition,
+ type EsSearch,
+} from "./esQueryBuilderModel";
+
+const tree: EsCondition = {
+ op: "bool",
+ conditions: [
+ { op: "term", field: "level", value: "error" },
+ {
+ op: "bool",
+ occur: "should",
+ conditions: [
+ { op: "match", field: "message", value: "timeout" },
+ { op: "exists", field: "trace.id" },
+ ],
+ },
+ ],
+};
+
+describe("condition tree edits", () => {
+ it("addresses a nested condition by its index path", () => {
+ expect(conditionAt(tree, [1, 0])).toEqual({
+ op: "match",
+ field: "message",
+ value: "timeout",
+ });
+ expect(conditionAt(tree, [])).toBe(tree);
+ expect(conditionAt(tree, [1, 7])).toBeUndefined();
+ });
+
+ it("replaces a nested condition without mutating the original tree", () => {
+ const next = updateAt(tree, [1, 0], (condition) => ({
+ ...condition,
+ value: "timed out",
+ }));
+ expect(conditionAt(next, [1, 0])?.value).toBe("timed out");
+ expect(conditionAt(tree, [1, 0])?.value).toBe("timeout");
+ // Untouched branches are shared, so React sees a changed identity only
+ // along the edited path.
+ expect(next.conditions?.[0]).toBe(tree.conditions?.[0]);
+ expect(next.conditions?.[1]).not.toBe(tree.conditions?.[1]);
+ });
+
+ it("inserts into a group at the requested position", () => {
+ const added = emptyCondition("keyword");
+ const next = insertAt(tree, [1], 1, added);
+ expect(next.conditions?.[1].conditions).toEqual([
+ { op: "match", field: "message", value: "timeout" },
+ added,
+ { op: "exists", field: "trace.id" },
+ ]);
+ expect(tree.conditions?.[1].conditions).toHaveLength(2);
+ });
+
+ it("appends when the position is past the end", () => {
+ const next = insertAt(tree, [], 99, emptyCondition("keyword"));
+ expect(next.conditions).toHaveLength(3);
+ expect(next.conditions?.[2].op).toBe("term");
+ });
+
+ it("removes a nested condition and leaves its siblings", () => {
+ const next = removeAt(tree, [1, 0]);
+ expect(next.conditions?.[1].conditions).toEqual([
+ { op: "exists", field: "trace.id" },
+ ]);
+ });
+
+ it("removing the root leaves an empty group rather than nothing", () => {
+ expect(removeAt(tree, [])).toEqual({ op: "bool", conditions: [] });
+ });
+});
+
+describe("condition defaults", () => {
+ it("picks the family's default operator", () => {
+ expect(emptyCondition("keyword").op).toBe("term");
+ expect(emptyCondition("text").op).toBe("match");
+ expect(emptyCondition("date").op).toBe("range");
+ expect(emptyCondition("number").op).toBe("range");
+ expect(emptyCondition("boolean").op).toBe("term");
+ });
+
+ it("defaults an unset occur to filter", () => {
+ expect(normalizeOccur(undefined)).toBe("filter");
+ expect(normalizeOccur("")).toBe("filter");
+ expect(normalizeOccur("must_not")).toBe("must_not");
+ });
+});
+
+describe("param operands", () => {
+ it("recognises a param reference and leaves literals alone", () => {
+ expect(isParamValue({ param: "level" })).toBe(true);
+ expect(isParamValue({ literal: { param: "level" } })).toBe(false);
+ expect(isParamValue("error")).toBe(false);
+ expect(isParamValue(undefined)).toBe(false);
+ expect(isParamValue({ param: "level", boost: 2 })).toBe(false);
+ });
+});
+
+describe("spec emptiness", () => {
+ const cases: Array<[string, EsSearch | undefined, boolean]> = [
+ ["undefined", undefined, true],
+ ["no keys", {}, true],
+ ["a bare match_all", { query: { op: "match_all" } }, true],
+ ["an empty root group", { query: { op: "bool", conditions: [] } }, true],
+ ["a group holding a leaf", { query: tree }, false],
+ ["sort only", { sort: [{ field: "@timestamp" }] }, false],
+ ["size only", { size: 50 }, false],
+ ["a preserved aggregation", { aggregations: { byLevel: {} } }, false],
+ ["a time field only", { timeField: "@timestamp" }, false],
+ ];
+ it.each(cases)("treats %s as empty=%s", (_name, spec, empty) => {
+ expect(isEmptySpec(spec)).toBe(empty);
+ });
+});
+
+describe("raw-DSL transition", () => {
+ // The server rejects a spec and a raw query together, so each transition has
+ // to clear the side it is leaving. Neither direction may leave both set.
+ it("hands the compiled DSL to the raw editor and drops the spec", () => {
+ expect(
+ toRawMode({ query: tree, size: 10 }, '{"query":{"match_all":{}}}'),
+ ).toEqual({ search: undefined, query: '{"query":{"match_all":{}}}' });
+ });
+
+ it("keeps the raw query when there is no compiled DSL to carry over", () => {
+ expect(toRawMode({ query: tree }, "", "{}")).toEqual({
+ search: undefined,
+ query: "{}",
+ });
+ });
+
+ it("starts the builder from an empty spec and clears the raw query", () => {
+ expect(toBuilderMode()).toEqual({
+ search: { query: { op: "bool", conditions: [] } },
+ query: "",
+ });
+ });
+});
+
+describe("fieldForParam", () => {
+ const bound: EsSearch = {
+ query: {
+ op: "bool",
+ conditions: [
+ { op: "term", field: "level", value: "error" },
+ {
+ op: "bool",
+ conditions: [
+ { op: "terms", field: "service.name", values: [{ param: "service" }] },
+ { op: "range", field: "@timestamp", gte: { param: "since" } },
+ ],
+ },
+ ],
+ },
+ };
+
+ it("reads the field off the condition a parameter is bound to", () => {
+ expect(fieldForParam(bound, "service")).toBe("service.name");
+ expect(fieldForParam(bound, "since")).toBe("@timestamp");
+ });
+
+ it("has no field for a parameter the specification never references", () => {
+ expect(fieldForParam(bound, "unused")).toBeUndefined();
+ expect(fieldForParam(bound, "")).toBeUndefined();
+ expect(fieldForParam(undefined, "service")).toBeUndefined();
+ });
+});
diff --git a/packages/ui/src/profiles/esQueryBuilderModel.ts b/packages/ui/src/profiles/esQueryBuilderModel.ts
new file mode 100644
index 00000000..c51e60e9
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryBuilderModel.ts
@@ -0,0 +1,251 @@
+/**
+ * Mirror of the Go `query/esdsl` specification. The builder edits this shape and
+ * the server compiles it; nothing here renders DSL, so the two never drift.
+ */
+
+export type EsOccur = "filter" | "must" | "should" | "must_not";
+
+/** A literal operand, or `{param}` binding one to a profile parameter. */
+export type EsValue = unknown;
+
+export type EsCondition = {
+ op: string;
+ occur?: EsOccur | "" | undefined;
+ field?: string | undefined;
+ fields?: string[] | undefined;
+ value?: EsValue | undefined;
+ values?: EsValue[] | undefined;
+ gt?: EsValue | undefined;
+ gte?: EsValue | undefined;
+ lt?: EsValue | undefined;
+ lte?: EsValue | undefined;
+ format?: string | undefined;
+ timeZone?: string | undefined;
+ analyzer?: string | undefined;
+ matchOperator?: string | undefined;
+ multiMatchType?: string | undefined;
+ fuzziness?: string | undefined;
+ slop?: number | undefined;
+ boost?: number | undefined;
+ caseInsensitive?: boolean | undefined;
+ escape?: boolean | undefined;
+ path?: string | undefined;
+ scoreMode?: string | undefined;
+ minimumShouldMatch?: string | undefined;
+ conditions?: EsCondition[] | undefined;
+ optional?: boolean | undefined;
+ when?: string | undefined;
+};
+
+export type EsSortBy = {
+ field: string;
+ order?: string | undefined;
+ mode?: string | undefined;
+ missing?: string | undefined;
+ unmappedType?: string | undefined;
+};
+
+export type EsSearch = {
+ query?: EsCondition | undefined;
+ sort?: EsSortBy[] | undefined;
+ size?: number | undefined;
+ from?: number | undefined;
+ source?:
+ | {
+ enabled?: boolean | undefined;
+ includes?: string[] | undefined;
+ excludes?: string[] | undefined;
+ }
+ | undefined;
+ trackTotalHits?:
+ | { enabled?: boolean | undefined; threshold?: number | undefined }
+ | undefined;
+ storedFields?: string[] | undefined;
+ fields?: string[] | undefined;
+ aggregations?: Record | undefined;
+ timeField?: string | undefined;
+};
+
+/** A path of child indexes from the root condition. `[]` is the root itself. */
+export type ConditionPath = number[];
+
+const defaultOperators: Record = {
+ keyword: "term",
+ text: "match",
+ date: "range",
+ number: "range",
+ boolean: "term",
+ ip: "term",
+ nested: "nested",
+};
+
+export function normalizeOccur(occur: string | undefined): EsOccur {
+ return (occur || "filter") as EsOccur;
+}
+
+/**
+ * defaultOperatorForFamily is the operator a family reads best as. It seeds a
+ * new condition and leads the operator list, so both agree by construction.
+ */
+export function defaultOperatorForFamily(family: string): string {
+ return defaultOperators[family] ?? "term";
+}
+
+export function emptyCondition(family = "keyword"): EsCondition {
+ const op = defaultOperatorForFamily(family);
+ return op === "nested" ? { op, conditions: [] } : { op };
+}
+
+export function emptyGroup(): EsCondition {
+ return { op: "bool", conditions: [] };
+}
+
+export function conditionAt(
+ root: EsCondition,
+ path: ConditionPath,
+): EsCondition | undefined {
+ let node: EsCondition | undefined = root;
+ for (const index of path) {
+ node = node?.conditions?.[index];
+ if (!node) return undefined;
+ }
+ return node;
+}
+
+/**
+ * updateAt rebuilds only the branch it edits, so untouched subtrees keep their
+ * identity and React re-renders just the changed rows.
+ */
+export function updateAt(
+ root: EsCondition,
+ path: ConditionPath,
+ update: (condition: EsCondition) => EsCondition,
+): EsCondition {
+ if (path.length === 0) return update(root);
+ const [index, ...rest] = path;
+ return {
+ ...root,
+ conditions: (root.conditions ?? []).map((child, position) =>
+ position === index ? updateAt(child, rest, update) : child,
+ ),
+ };
+}
+
+export function insertAt(
+ root: EsCondition,
+ groupPath: ConditionPath,
+ position: number,
+ condition: EsCondition,
+): EsCondition {
+ return updateAt(root, groupPath, (group) => {
+ const children = [...(group.conditions ?? [])];
+ children.splice(Math.min(Math.max(position, 0), children.length), 0, condition);
+ return { ...group, conditions: children };
+ });
+}
+
+export function removeAt(root: EsCondition, path: ConditionPath): EsCondition {
+ if (path.length === 0) return emptyGroup();
+ const index = path[path.length - 1];
+ return updateAt(root, path.slice(0, -1), (group) => ({
+ ...group,
+ conditions: (group.conditions ?? []).filter(
+ (_child, position) => position !== index,
+ ),
+ }));
+}
+
+/** isParamValue reports whether an operand binds a profile parameter. */
+export function isParamValue(value: EsValue): value is { param: string } {
+ if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+ const keys = Object.keys(value as Record);
+ return (
+ keys.length === 1 &&
+ keys[0] === "param" &&
+ typeof (value as { param: unknown }).param === "string"
+ );
+}
+
+export function paramName(value: EsValue): string | undefined {
+ return isParamValue(value) ? value.param : undefined;
+}
+
+/**
+ * fieldForParam is the field a parameter filters on: the field of the first
+ * condition whose operand binds it. A parameter the specification never
+ * references has no field, and so nothing to offer values from.
+ */
+export function fieldForParam(
+ search: EsSearch | undefined,
+ name: string,
+): string | undefined {
+ const walk = (condition: EsCondition | undefined): string | undefined => {
+ if (!condition) return undefined;
+ const operands: EsValue[] = [
+ condition.value,
+ ...(condition.values ?? []),
+ condition.gt,
+ condition.gte,
+ condition.lt,
+ condition.lte,
+ ];
+ if (condition.field && operands.some((value) => paramName(value) === name)) {
+ return condition.field;
+ }
+ for (const child of condition.conditions ?? []) {
+ const found = walk(child);
+ if (found) return found;
+ }
+ return undefined;
+ };
+ return name ? walk(search?.query) : undefined;
+}
+
+/**
+ * isEmptySpec reports whether a specification says nothing the raw query would
+ * not. It is what decides whether a profile is still in raw mode.
+ */
+export function isEmptySpec(search: EsSearch | undefined): boolean {
+ if (!search) return true;
+ const { query, ...rest } = search;
+ for (const value of Object.values(rest)) {
+ if (Array.isArray(value) ? value.length > 0 : value !== undefined && value !== null) {
+ if (typeof value === "object" && !Array.isArray(value)) {
+ if (Object.keys(value as object).length > 0) return false;
+ continue;
+ }
+ return false;
+ }
+ }
+ return isEmptyCondition(query);
+}
+
+function isEmptyCondition(condition: EsCondition | undefined): boolean {
+ if (!condition) return true;
+ if (condition.op === "match_all") return true;
+ if (condition.op !== "bool") return false;
+ return (condition.conditions ?? []).every(isEmptyCondition);
+}
+
+export type QueryModeTransition = {
+ search: EsSearch | undefined;
+ query: string;
+};
+
+/**
+ * toRawMode leaves the builder for the raw editor, seeding it with the DSL the
+ * specification last compiled to. The specification is dropped, never kept
+ * alongside the query: the server treats holding both as an authoring error.
+ */
+export function toRawMode(
+ _search: EsSearch | undefined,
+ compiled: string,
+ currentQuery = "",
+): QueryModeTransition {
+ return { search: undefined, query: compiled.trim() || currentQuery };
+}
+
+/** toBuilderMode is the inverse: the raw query is dropped, not parsed. */
+export function toBuilderMode(search?: EsSearch): QueryModeTransition {
+ return { search: search ?? { query: emptyGroup() }, query: "" };
+}
diff --git a/packages/ui/src/profiles/esQueryClauseGroup.test.tsx b/packages/ui/src/profiles/esQueryClauseGroup.test.tsx
new file mode 100644
index 00000000..2f41396b
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryClauseGroup.test.tsx
@@ -0,0 +1,159 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { EsQueryClauseGroup } from "./esQueryClauseGroup";
+import { groupOperatorOptions, isGroupOperator } from "./esQueryGroupModel";
+import type { EsQueryContext, EsQueryTreeActions } from "./esQueryConditionRow";
+import type { EsCondition } from "./esQueryBuilderModel";
+import type {
+ EsBuilderVocabulary,
+ EsFieldMapping,
+ EsOperatorInfo,
+} from "./esQueryOperators";
+
+const catalog: EsOperatorInfo[] = [
+ { op: "term", label: "is", arity: "single", needsField: true,
+ fieldTypes: ["keyword", "text", "date", "number", "boolean", "ip"] },
+ { op: "match", label: "matches", arity: "single", needsField: true,
+ fieldTypes: ["text", "keyword"], analyzed: true },
+ { op: "exists", label: "exists", arity: "none", needsField: true, fieldTypes: ["any"] },
+ { op: "nested", label: "nested", arity: "group", fieldTypes: ["nested"], group: true },
+ { op: "bool", label: "group", arity: "group", fieldTypes: ["any"], group: true },
+];
+
+const vocabulary: EsBuilderVocabulary = {
+ catalog,
+ occurs: ["filter", "must", "should", "must_not"],
+ qualifierNames: ["boost"],
+ qualifiers: { boost: { type: "number", title: "Boost" } },
+ sortOrders: ["asc", "desc"],
+};
+
+const fields: EsFieldMapping[] = [
+ { name: "level", dataType: "keyword", searchable: true, aggregatable: true },
+ { name: "message", dataType: "text", searchable: true, aggregatable: false },
+ { name: "spans", dataType: "nested", searchable: true, aggregatable: false },
+];
+
+const noopActions: EsQueryTreeActions = {
+ update: () => undefined,
+ insert: () => undefined,
+ remove: () => undefined,
+ mapParam: () => undefined,
+ unmapParam: () => undefined,
+};
+
+const render = (condition: EsCondition, root = true) => {
+ const context: EsQueryContext = { fields, vocabulary, params: [] };
+ return renderToStaticMarkup(
+ ) =>
+ actions.update(path, (current) => applyPatch(current, patch));
+ // A should clause alongside anything else matches one by default. Offering the
+ // override only once a should exists keeps it out of the way until it means
+ // something.
+ const hasShould = children.some(
+ (child) => normalizeOccur(child.occur) === "should",
+ );
+
+ return (
+
+
+ {root ? (
+ Match
+ ) : (
+ <>
+
+ set({ occur: event.target.value as never })}
+ />
+
+
+ set({ op: event.target.value })}
+ />
+
+
+ )}
+ {condition.op === "nested" ? (
+ set({ path: next })}
+ options={nestedPathOptions(context.fields)}
+ placeholder="Nested path…"
+ allowCustomValue
+ />
+ ) : null}
+ {hasShould ? (
+
+ set({ minimumShouldMatch: next === "" ? undefined : next })
+ }
+ />
+ ) : null}
+
+ actions.insert(path, emptyCondition())}
+ >
+
+ actions.insert(path, emptyGroup())}
+ >
+
+ {root ? null : (
+ actions.remove(path)}
+ />
+ )}
+
+
+ {children.length === 0 ? (
+
+ No conditions — every document matches.
+
+ ) : (
+
+ {children.map((child, index) =>
+ isGroupOperator(context.vocabulary.catalog, child.op) ? (
+
+ )}
+
;
+ roles?: Record;
+};
+
+export type EsCompileRequest = EsCompileInput & {
+ baseUrl: string;
+ enabled?: boolean;
+ debounceMs?: number;
+};
+
+/** compileRequestBody is what POST /compile takes, with the empty parts left off. */
+export function compileRequestBody(input: EsCompileInput): string {
+ const { search, params, roles } = input;
+ return JSON.stringify({
+ search,
+ ...(params && Object.keys(params).length ? { params } : {}),
+ ...(roles && Object.keys(roles).length ? { roles } : {}),
+ });
+}
+
+export function errorMessage(error: unknown): string | undefined {
+ if (!error) return undefined;
+ return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * useCompiledSearch compiles the specification as it is edited. The body is
+ * debounced rather than the request, so an edit that lands back on a body
+ * already compiled costs nothing.
+ */
+export function useCompiledSearch(input: EsCompileRequest): EsCompilation {
+ const { baseUrl, enabled = true, debounceMs = 250 } = input;
+ const body = compileRequestBody(input);
+ const [settled, setSettled] = useState(body);
+ useEffect(() => {
+ const timer = setTimeout(() => setSettled(body), debounceMs);
+ return () => clearTimeout(timer);
+ }, [body, debounceMs]);
+
+ const compiled = useQuery({
+ queryKey: ["es-compile", baseUrl, settled],
+ queryFn: () =>
+ fetchJSON(`${baseUrl}/compile`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: settled,
+ }),
+ enabled: enabled && baseUrl !== "",
+ retry: 0,
+ });
+
+ return {
+ query: compiled.data?.query ?? "",
+ ...(compiled.data ? { size: compiled.data.size, from: compiled.data.from } : {}),
+ ...(compiled.error ? { error: errorMessage(compiled.error) } : {}),
+ loading: compiled.isFetching,
+ };
+}
diff --git a/packages/ui/src/profiles/esQueryConditionRow.test.tsx b/packages/ui/src/profiles/esQueryConditionRow.test.tsx
new file mode 100644
index 00000000..83f73f53
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryConditionRow.test.tsx
@@ -0,0 +1,207 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { EsQueryConditionRow, type EsQueryContext, type EsQueryTreeActions } from "./esQueryConditionRow";
+import { occurOptions } from "./esQueryOccur";
+import type { EsCondition } from "./esQueryBuilderModel";
+import type {
+ EsBuilderVocabulary,
+ EsFieldMapping,
+ EsOperatorInfo,
+} from "./esQueryOperators";
+
+const catalog: EsOperatorInfo[] = [
+ { op: "term", label: "is", arity: "single", needsField: true,
+ fieldTypes: ["keyword", "text", "date", "number", "boolean", "ip"] },
+ { op: "terms", label: "is one of", arity: "multiple", needsField: true,
+ fieldTypes: ["keyword", "text", "date", "number", "boolean", "ip"] },
+ { op: "match", label: "matches", arity: "single", needsField: true,
+ fieldTypes: ["text", "keyword"], analyzed: true },
+ { op: "range", label: "is between", arity: "range", needsField: true,
+ fieldTypes: ["date", "number", "ip", "keyword"] },
+ { op: "exists", label: "exists", arity: "none", needsField: true, fieldTypes: ["any"] },
+];
+
+const vocabulary: EsBuilderVocabulary = {
+ catalog,
+ occurs: ["filter", "must", "should", "must_not"],
+ qualifierNames: ["boost", "caseInsensitive", "scoreMode"],
+ qualifierRestrictions: { caseInsensitive: ["term"], scoreMode: ["nested"] },
+ qualifiers: {
+ boost: { type: "number", title: "Boost" },
+ caseInsensitive: { type: "boolean", title: "Case insensitive" },
+ scoreMode: { type: "string", title: "Score mode", enum: ["avg", "none"] },
+ },
+ sortOrders: ["asc", "desc"],
+};
+
+const fields: EsFieldMapping[] = [
+ { name: "level", dataType: "keyword", searchable: true, aggregatable: true },
+ { name: "message", dataType: "text", searchable: true, aggregatable: false },
+ { name: "@timestamp", dataType: "date", searchable: true, aggregatable: true },
+ {
+ name: "code",
+ types: ["keyword", "long"],
+ conflicting: true,
+ searchable: true,
+ aggregatable: true,
+ },
+];
+
+const noopActions: EsQueryTreeActions = {
+ update: () => undefined,
+ insert: () => undefined,
+ remove: () => undefined,
+ mapParam: () => undefined,
+ unmapParam: () => undefined,
+};
+
+const render = (condition: EsCondition, params: string[] = []) => {
+ const context: EsQueryContext = {
+ fields,
+ vocabulary,
+ params: params.map((name) => ({ name })),
+ };
+ return renderToStaticMarkup(
+ , so the clause and operator controls do
+ * not read each other's options. */
+const selectMarkup = (html: string, ariaLabel: string): string => {
+ const start = html.indexOf(`aria-label="${ariaLabel}"`);
+ expect(start, `no select labelled ${ariaLabel}`).toBeGreaterThan(-1);
+ return html.slice(start, html.indexOf(" ", start));
+};
+
+/** The operator values the rendered offers, in document order. */
+const offeredOperators = (html: string): string[] =>
+ Array.from(
+ selectMarkup(html, "Operator").matchAll(/ match[1]);
+
+describe("clause labels", () => {
+ // filter and must both narrow the hits; only must contributes to the score,
+ // which the raw bool clause names do not say out loud.
+ it("names each bool clause the way an author reads it", () => {
+ expect(occurOptions(["filter", "must", "should", "must_not"])).toEqual([
+ { value: "filter", label: "AND" },
+ { value: "must", label: "AND (scored)" },
+ { value: "should", label: "OR" },
+ { value: "must_not", label: "NOT" },
+ ]);
+ });
+
+ it("passes an unknown clause through rather than dropping it", () => {
+ expect(occurOptions(["filter_v2"])).toEqual([
+ { value: "filter_v2", label: "filter_v2" },
+ ]);
+ });
+});
+
+describe("operators offered per field", () => {
+ it("leads a keyword field with the exact operators", () => {
+ expect(offeredOperators(render({ op: "term", field: "level" }))).toEqual([
+ "term",
+ "terms",
+ "range",
+ "exists",
+ "match",
+ ]);
+ });
+
+ // A text field is analyzed, so term matches tokens rather than the stored
+ // text. It stays offered, but behind the Advanced divider.
+ it("leads a text field with match and demotes the exact operators", () => {
+ const html = render({ op: "match", field: "message" });
+ expect(offeredOperators(html)).toEqual(["match", "exists", "term", "terms"]);
+ expect(html).toContain(' ');
+ expect(html.indexOf('value="match"')).toBeLessThan(
+ html.indexOf(''),
+ );
+ });
+
+ // Changing the field must never blank the operator control, so an operator
+ // the new field does not suit is still offered — under Advanced.
+ it("keeps the current operator when the field does not suit it", () => {
+ const html = render({ op: "match", field: "@timestamp" });
+ expect(offeredOperators(html)).toContain("match");
+ expect(html).toContain('');
+ });
+});
+
+describe("operand editors", () => {
+ it("renders a chip input for a multi-value operator", () => {
+ const html = render({ op: "terms", field: "level", values: ["warn", "error"] });
+ expect(html).toContain('aria-label="Add value"');
+ expect(html).toContain("es-value-chip");
+ expect(html).toContain("warn");
+ expect(html).toContain("error");
+ });
+
+ it("renders both bounds of a range with date math presets", () => {
+ const html = render({ op: "range", field: "@timestamp", gte: "now-1h" });
+ expect(html).toContain('aria-label="From"');
+ expect(html).toContain('aria-label="To"');
+ expect(html).toContain('value="now-15m"');
+ });
+
+ it("offers no date math on a field that is not a date", () => {
+ expect(render({ op: "range", field: "level" })).not.toContain('value="now-15m"');
+ });
+
+ it("renders no operand at all for a presence test", () => {
+ const html = render({ op: "exists", field: "level" });
+ expect(html).not.toContain('aria-label="Value"');
+ });
+
+ // A bound operand is substituted structurally at compile time. Showing the
+ // parameter rather than an editable box is what keeps that visible.
+ it("renders a parameter chip in place of a bound value", () => {
+ const html = render({ op: "term", field: "level", value: { param: "severity" } });
+ expect(html).toContain("es-param-chip");
+ expect(html).toContain("severity");
+ expect(html).not.toContain('aria-label="Value"');
+ });
+
+ it("offers a parameter binder only where the profile declares parameters", () => {
+ expect(render({ op: "term", field: "level" }, ["severity"])).toContain(
+ 'aria-label="Bind Value to a parameter"',
+ );
+ expect(render({ op: "term", field: "level" })).not.toContain(
+ "to a parameter",
+ );
+ });
+});
+
+describe("field warnings", () => {
+ it("warns inline about a field mapped differently across indexes", () => {
+ const html = render({ op: "term", field: "code" });
+ expect(html).toContain('role="alert"');
+ expect(html).toContain("code is mapped as keyword and long across indexes");
+ });
+
+ it("stays quiet about an ordinary field", () => {
+ expect(render({ op: "term", field: "level" })).not.toContain('role="alert"');
+ });
+});
+
+describe("advanced qualifiers", () => {
+ it("offers only the qualifiers the operator emits", () => {
+ const html = render({ op: "term", field: "level" });
+ expect(html).toContain("Case insensitive");
+ expect(html).toContain('aria-label="Boost"');
+ expect(html).not.toContain("Score mode");
+ });
+
+ it("drops a restricted qualifier for an operator that does not emit it", () => {
+ const html = render({ op: "match", field: "message" });
+ expect(html).not.toContain("Case insensitive");
+ expect(html).toContain('aria-label="Boost"');
+ });
+});
diff --git a/packages/ui/src/profiles/esQueryConditionRow.tsx b/packages/ui/src/profiles/esQueryConditionRow.tsx
new file mode 100644
index 00000000..f5169831
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryConditionRow.tsx
@@ -0,0 +1,245 @@
+/**
+ * One leaf condition: which field, which operator, and the operand that
+ * operator takes. Which operators a field may use and which advanced qualifiers
+ * an operator emits both come from the schema vocabulary, so this file owns the
+ * editing surface and never the vocabulary itself.
+ */
+
+import { Combobox } from "../components/Combobox";
+import { IconButton } from "../components/IconButton";
+import { MultiSelect } from "../components/MultiSelect";
+import { Select } from "../components/select";
+import { UiTrash } from "../icons";
+import type { ConditionPath, EsCondition } from "./esQueryBuilderModel";
+import { applyPatch, type Patch } from "./profileWizardModel";
+import type { ParamOperand } from "./esParamMappingModel";
+import type { FieldValuesQuery } from "./esFieldValues";
+import { ConditionOperand, QualifierInput } from "./esQueryOperandEditors";
+import type { ParamDraft } from "./profileWizardModel";
+import {
+ changeConditionOperator,
+ fieldWarning,
+ operatorsForField,
+ qualifiersForOperator,
+ type EsBuilderVocabulary,
+ type EsFieldMapping,
+} from "./esQueryOperators";
+import { occurOptions } from "./esQueryOccur";
+
+export type EsQueryContext = {
+ fields: EsFieldMapping[];
+ vocabulary: EsBuilderVocabulary;
+ /** Declared profile parameters an operand can bind to. */
+ params: ParamDraft[];
+ /**
+ * The values a row's field holds, scoped by the builder to the rest of the
+ * query. Absent where the host has no connection to ask.
+ */
+ values?: (request: {
+ path: ConditionPath;
+ field: string;
+ }) => FieldValuesQuery | undefined;
+};
+
+/**
+ * The edits a condition row or group asks for, addressed by path. The builder
+ * owns the tree and applies them; every node below it is stateless.
+ */
+export type EsQueryTreeActions = {
+ update: (
+ path: ConditionPath,
+ update: (condition: EsCondition) => EsCondition,
+ ) => void;
+ insert: (groupPath: ConditionPath, condition: EsCondition) => void;
+ remove: (path: ConditionPath) => void;
+ mapParam: (path: ConditionPath, operand: ParamOperand, name: string) => void;
+ unmapParam: (path: ConditionPath, name: string) => void;
+};
+
+export function EsQueryConditionRow({
+ condition,
+ path,
+ context,
+ actions,
+}: {
+ condition: EsCondition;
+ path: ConditionPath;
+ context: EsQueryContext;
+ actions: EsQueryTreeActions;
+}) {
+ const { catalog, qualifierNames, qualifierRestrictions, qualifiers } =
+ context.vocabulary;
+ const field = context.fields.find((entry) => entry.name === condition.field);
+ const info = catalog.find((entry) => entry.op === condition.op);
+ const warning = field ? fieldWarning(field) : undefined;
+ const set = (patch: Patch) =>
+ actions.update(path, (current) => applyPatch(current, patch));
+ const rowId = path.join("-") || "root";
+ const values = condition.field
+ ? context.values?.({ path, field: condition.field })
+ : undefined;
+
+ const advanced = qualifiersForOperator({
+ names: qualifierNames,
+ ...(qualifierRestrictions ? { restrictions: qualifierRestrictions } : {}),
+ op: condition.op,
+ });
+
+ return (
+
+
+
+ set({ occur: event.target.value as never })}
+ />
+
+ {info?.needsField ? (
+ set({ field: next })}
+ options={fieldOptions(context.fields)}
+ placeholder="Field…"
+ />
+ ) : null}
+ {info?.acceptsFields ? (
+ set({ fields: next })}
+ options={context.fields.map((entry) => ({
+ value: entry.name,
+ label: entry.name,
+ }))}
+ placeholder="All fields"
+ />
+ ) : null}
+
+ {
+ const next = catalog.find(
+ (entry) => entry.op === event.target.value,
+ );
+ if (!next) {
+ throw new Error(
+ `operator ${event.target.value} is missing from the catalog`,
+ );
+ }
+ actions.update(path, (current) =>
+ changeConditionOperator(current, next),
+ );
+ }}
+ >
+ {operatorGroups(catalog, field, condition.op).map((group) => {
+ const options = group.operators.map((entry) => (
+
+ {entry.label}
+
+ ));
+ return group.label ? (
+
+ {options}
+
+ ) : (
+ options
+ );
+ })}
+
+
+ actions.mapParam(path, operand, name)}
+ onUnbindParam={(name) => actions.unmapParam(path, name)}
+ />
+ actions.remove(path)}
+ />
+
+ {warning ? (
+
+ {warning}
+
+ ) : null}
+ {advanced.length ? (
+
+
+ Advanced
+
+
+ {advanced.map((name) => (
+ )[name]}
+ onChange={(next) => set({ [name]: next } as Patch)}
+ />
+ ))}
+
+
+
+
+ ) : null}
+
= {
+ filter: "AND",
+ must: "AND (scored)",
+ should: "OR",
+ must_not: "NOT"
+};
diff --git a/packages/ui/src/profiles/esQueryOperandEditors.tsx b/packages/ui/src/profiles/esQueryOperandEditors.tsx
new file mode 100644
index 00000000..08174c0c
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryOperandEditors.tsx
@@ -0,0 +1,338 @@
+/**
+ * The operand side of a condition row: the value an operator takes, and the
+ * advanced qualifiers it emits alongside it. Which operand shape applies comes
+ * from the operator's arity, and which qualifiers exist comes from the schema —
+ * neither is decided here.
+ */
+
+import { InputField } from "../components/InputField";
+import { Select } from "../components/select";
+import { useState, type ReactNode } from "react";
+import {
+ isParamValue,
+ type EsCondition,
+ type EsValue,
+} from "./esQueryBuilderModel";
+import type { FieldValuesQuery } from "./esFieldValues";
+import type { Patch } from "./profileWizardModel";
+import type { ParamOperand } from "./esParamMappingModel";
+import { extendEsParamOperand } from "./esParamOperandExtension";
+import {
+ conditionOperandPatch,
+ multipleConditionValues,
+} from "./esQueryOperandModel";
+import type { EsQualifierSchema } from "./esQueryOperators";
+import { ValueCombobox, ValuesCombobox } from "./esValueCombobox";
+import type { ParamDraft } from "./profileWizardModel";
+
+// Date math a range over a date field commonly starts from. They are ordinary
+// operand values that the backend resolves — this only saves the typing.
+const dateMathPresets = [
+ "now-15m",
+ "now-1h",
+ "now-24h",
+ "now-7d",
+ "now/d",
+ "now",
+];
+
+export function ConditionOperand({
+ condition,
+ arity,
+ rowId,
+ params,
+ dateMath,
+ values,
+ set,
+ onBindParam,
+ onUnbindParam,
+}: {
+ condition: EsCondition;
+ arity: string;
+ rowId: string;
+ params: ParamDraft[];
+ dateMath: boolean;
+ /** The field's own values, when the mapping allows aggregating them. */
+ values?: FieldValuesQuery;
+ set: (patch: Patch) => void;
+ onBindParam: (operand: ParamOperand, name: string) => void;
+ onUnbindParam: (name: string) => void;
+}) {
+ if (arity === "none" || arity === "group") return null;
+ if (arity === "multiple") {
+ return (
+ {
+ if (isParamValue(next)) return onBindParam("values", next.param);
+ const bound = boundParam(multipleConditionValues(condition));
+ if (next === undefined && bound) return onUnbindParam(bound);
+ if (!Array.isArray(next))
+ throw new Error("multiple operand requires a value list");
+ set(conditionOperandPatch({ arity: "multiple", values: next }));
+ }}
+ />
+ );
+ }
+ if (arity === "range") {
+ return (
+
+ {(["gte", "lte"] as const).map((bound) => (
+ {
+ if (isParamValue(next)) return onBindParam(bound, next.param);
+ const mapped = boundParam(condition[bound]);
+ if (next === undefined && mapped) return onUnbindParam(mapped);
+ set(
+ conditionOperandPatch({ arity: "range", bound, value: next }),
+ );
+ }}
+ />
+ ))}
+
+ );
+ }
+ return (
+ {
+ if (isParamValue(next)) return onBindParam("value", next.param);
+ const bound = boundParam(condition.value);
+ if (next === undefined && bound) return onUnbindParam(bound);
+ set(conditionOperandPatch({ arity: "single", value: next }));
+ }}
+ />
+ );
+}
+
+function ValueInput({
+ id,
+ label,
+ value,
+ params,
+ presets,
+ lookup,
+ onChange,
+}: {
+ id: string;
+ label: string;
+ value: EsValue;
+ params: ParamDraft[];
+ presets: string[];
+ lookup?: FieldValuesQuery;
+ onChange: (next: EsValue) => void;
+}) {
+ let node: ReactNode;
+ if (lookup) {
+ node = (
+ onChange(next === "" ? undefined : next)}
+ />
+ );
+ } else {
+ const listId = presets.length ? `es-presets-${id}` : undefined;
+ node = (
+ <>
+ onChange(next === "" ? undefined : next)}
+ />
+ {listId ? (
+
+ {presets.map((preset) => (
+
+ ) : null}
+
+ );
+ }
+ return extendEsParamOperand({
+ label,
+ value,
+ onChange,
+ node,
+ params,
+ });
+}
+
+function ValuesInput({
+ values,
+ params,
+ lookup,
+ onChange,
+}: {
+ values: EsValue[];
+ params: ParamDraft[];
+ lookup?: FieldValuesQuery;
+ onChange: (values: EsValue[] | EsValue | undefined) => void;
+}) {
+ const [draft, setDraft] = useState("");
+ const bound = values.filter(isParamValue);
+ const literals = values.filter((value) => !isParamValue(value));
+ let node: ReactNode;
+ if (lookup) {
+ node = (
+ onChange([...next, ...bound])}
+ />
+ );
+ } else {
+ const commit = () => {
+ const parsed = draft
+ .split(",")
+ .map((entry) => entry.trim())
+ .filter(Boolean);
+ if (!parsed.length) return;
+ onChange([...literals, ...parsed, ...bound]);
+ setDraft("");
+ };
+ const removeAt = (index: number) =>
+ onChange([
+ ...literals.filter((_value, position) => position !== index),
+ ...bound,
+ ]);
+ node = (
+
+ {literals.map((value, index) => (
+
+ {String(value)}
+ removeAt(index)}
+ >
+ ×
+
+
+ ))}
+ {
+ if (event.key !== "Enter" && event.key !== ",") return;
+ event.preventDefault();
+ commit();
+ }}
+ onBlur={commit}
+ />
+
+ );
+ }
+ return extendEsParamOperand({
+ label: "value",
+ value: values,
+ onChange,
+ node,
+ params,
+ });
+}
+
+function boundParam(value: EsValue | EsValue[]): string | undefined {
+ const values = Array.isArray(value) ? value : [value];
+ return values.find(isParamValue)?.param;
+}
+
+export function QualifierInput({
+ name,
+ schema,
+ value,
+ onChange,
+}: {
+ name: string;
+ schema: EsQualifierSchema;
+ value: unknown;
+ onChange: (next: unknown) => void;
+}) {
+ const label = schema.title ?? name;
+ if (schema.type === "boolean") {
+ const checked =
+ value === undefined ? schema.default === true : value === true;
+ return (
+
+
+ );
+ }
+ if (schema.enum?.length) {
+ // Select renders `placeholder` as a disabled option, which would trap the
+ // qualifier once set. An explicit empty entry is what clears it again.
+ return (
+
+ ({ value: entry, label: entry })),
+ ]}
+ onChange={(event) =>
+ onChange(event.target.value === "" ? undefined : event.target.value)
+ }
+ />
+
+ );
+ }
+ const numeric = schema.type === "integer" || schema.type === "number";
+ return (
+ {
+ if (next === "") return onChange(undefined);
+ onChange(numeric ? Number(next) : next);
+ }}
+ />
+ );
+}
diff --git a/packages/ui/src/profiles/esQueryOperandModel.test.ts b/packages/ui/src/profiles/esQueryOperandModel.test.ts
new file mode 100644
index 00000000..6cd9aabc
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryOperandModel.test.ts
@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import {
+ conditionOperandPatch,
+ multipleConditionValues,
+} from "./esQueryOperandModel";
+import { changeConditionOperator, type EsOperatorInfo } from "./esQueryOperators";
+
+describe("multipleConditionValues", () => {
+ it("uses canonical values ahead of a stale singular operand", () => {
+ expect(
+ multipleConditionValues({
+ op: "terms",
+ value: "stale",
+ values: ["scheme-1", "scheme-2"],
+ }),
+ ).toEqual(["scheme-1", "scheme-2"]);
+ });
+
+ it("shows a valid singular terms operand as one selected value", () => {
+ expect(multipleConditionValues({ op: "terms", value: "scheme-1" })).toEqual([
+ "scheme-1",
+ ]);
+ expect(multipleConditionValues({ op: "terms" })).toEqual([]);
+ });
+});
+
+describe("conditionOperandPatch", () => {
+ it("never leaves value beside values after the term to terms editing flow", () => {
+ const terms: EsOperatorInfo = {
+ op: "terms",
+ label: "is one of",
+ arity: "multiple",
+ needsField: true,
+ fieldTypes: ["keyword"],
+ };
+ const changed = changeConditionOperator(
+ { op: "term", field: "tag.scheme@id", value: "scheme-1" },
+ terms,
+ );
+
+ expect({
+ ...changed,
+ ...conditionOperandPatch({
+ arity: "multiple",
+ values: [...multipleConditionValues(changed), "scheme-2"],
+ }),
+ }).toEqual({
+ op: "terms",
+ field: "tag.scheme@id",
+ value: undefined,
+ values: ["scheme-1", "scheme-2"],
+ gt: undefined,
+ gte: undefined,
+ lt: undefined,
+ lte: undefined,
+ conditions: undefined,
+ });
+ });
+
+ it("makes a multiple edit the only operand representation", () => {
+ expect(
+ conditionOperandPatch({
+ arity: "multiple",
+ values: ["scheme-1", "scheme-2"],
+ }),
+ ).toEqual({
+ value: undefined,
+ values: ["scheme-1", "scheme-2"],
+ gt: undefined,
+ gte: undefined,
+ lt: undefined,
+ lte: undefined,
+ conditions: undefined,
+ });
+ });
+
+ it("clears list and range operands for a singular edit", () => {
+ expect(conditionOperandPatch({ arity: "single", value: "error" })).toEqual({
+ value: "error",
+ values: undefined,
+ gt: undefined,
+ gte: undefined,
+ lt: undefined,
+ lte: undefined,
+ conditions: undefined,
+ });
+ });
+
+ it("keeps sibling bounds while clearing scalar and list operands", () => {
+ expect(
+ conditionOperandPatch({ arity: "range", bound: "gte", value: "now-1h" }),
+ ).toEqual({
+ value: undefined,
+ values: undefined,
+ conditions: undefined,
+ gte: "now-1h",
+ });
+ });
+});
diff --git a/packages/ui/src/profiles/esQueryOperandModel.ts b/packages/ui/src/profiles/esQueryOperandModel.ts
new file mode 100644
index 00000000..b513f627
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryOperandModel.ts
@@ -0,0 +1,39 @@
+import type { EsCondition, EsValue } from "./esQueryBuilderModel";
+import type { Patch } from "./profileWizardModel";
+
+type ConditionOperandEdit =
+ | { arity: "single"; value: EsValue }
+ | { arity: "multiple"; values: EsValue[] }
+ | {
+ arity: "range";
+ bound: "gt" | "gte" | "lt" | "lte";
+ value: EsValue;
+ };
+
+export function multipleConditionValues(condition: EsCondition): EsValue[] {
+ if (condition.values?.length) return condition.values;
+ return condition.value === undefined ? [] : [condition.value];
+}
+
+export function conditionOperandPatch(
+ edit: ConditionOperandEdit,
+): Patch {
+ if (edit.arity === "range") {
+ return {
+ value: undefined,
+ values: undefined,
+ conditions: undefined,
+ [edit.bound]: edit.value,
+ };
+ }
+ const cleared = {
+ gt: undefined,
+ gte: undefined,
+ lt: undefined,
+ lte: undefined,
+ conditions: undefined,
+ };
+ return edit.arity === "multiple"
+ ? { value: undefined, values: edit.values, ...cleared }
+ : { value: edit.value, values: undefined, ...cleared };
+}
diff --git a/packages/ui/src/profiles/esQueryOperators.test.ts b/packages/ui/src/profiles/esQueryOperators.test.ts
new file mode 100644
index 00000000..ea04bd72
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryOperators.test.ts
@@ -0,0 +1,348 @@
+import { describe, expect, it } from "vitest";
+import {
+ changeConditionOperator,
+ esBuilderVocabulary,
+ fieldFamily,
+ fieldWarning,
+ operatorCatalogFromSchema,
+ operatorsForField,
+ qualifiersForOperator,
+ sortableFields,
+ type EsFieldMapping,
+ type EsOperatorInfo,
+} from "./esQueryOperators";
+
+// A trimmed catalog in the exact shape x-es-operators carries. Using the real
+// keys keeps the test honest about what the schema actually hands over.
+const catalog: EsOperatorInfo[] = [
+ { op: "term", label: "is", arity: "single", needsField: true,
+ fieldTypes: ["keyword", "text", "date", "number", "boolean", "ip"] },
+ { op: "terms", label: "is one of", arity: "multiple", needsField: true,
+ fieldTypes: ["keyword", "text", "date", "number", "boolean", "ip"] },
+ { op: "match", label: "matches", arity: "single", needsField: true,
+ fieldTypes: ["text", "keyword"], analyzed: true },
+ { op: "prefix", label: "starts with", arity: "single", needsField: true,
+ fieldTypes: ["keyword", "text"] },
+ { op: "range", label: "is between", arity: "range", needsField: true,
+ fieldTypes: ["date", "number", "ip", "keyword"] },
+ { op: "exists", label: "exists", arity: "none", needsField: true, fieldTypes: ["any"] },
+ { op: "query_string", label: "query string", arity: "single", acceptsFields: true,
+ fieldTypes: ["any"], analyzed: true },
+ { op: "nested", label: "nested", arity: "group", fieldTypes: ["nested"], group: true },
+ { op: "bool", label: "group", arity: "group", fieldTypes: ["any"], group: true },
+];
+
+const field = (mapping: Partial & { name: string }): EsFieldMapping => ({
+ searchable: true,
+ aggregatable: true,
+ ...mapping,
+});
+
+describe("condition operator transitions", () => {
+ const operator = (op: string) => {
+ const match = catalog.find((entry) => entry.op === op);
+ if (!match) throw new Error(`missing test operator ${op}`);
+ return match;
+ };
+
+ it("moves a singular operand into values when changing to terms", () => {
+ expect(
+ changeConditionOperator(
+ {
+ op: "term",
+ occur: "filter",
+ field: "tag.scheme@id",
+ value: "scheme-1",
+ boost: 2,
+ },
+ operator("terms"),
+ ),
+ ).toEqual({
+ op: "terms",
+ occur: "filter",
+ field: "tag.scheme@id",
+ values: ["scheme-1"],
+ boost: 2,
+ });
+ });
+
+ it("promotes one list operand when changing to a singular operator", () => {
+ expect(
+ changeConditionOperator(
+ { op: "terms", field: "level", values: ["error"] },
+ operator("term"),
+ ),
+ ).toEqual({ op: "term", field: "level", value: "error" });
+ });
+
+ it("clears a list that cannot be converted to one operand", () => {
+ expect(
+ changeConditionOperator(
+ { op: "terms", field: "level", values: ["warn", "error"] },
+ operator("term"),
+ ),
+ ).toEqual({ op: "term", field: "level" });
+ });
+
+ it("keeps only operands accepted by the next arity", () => {
+ expect(
+ changeConditionOperator(
+ {
+ op: "range",
+ field: "@timestamp",
+ value: "stale",
+ values: ["also-stale"],
+ gte: "now-1h",
+ lte: "now",
+ conditions: [{ op: "exists", field: "trace.id" }],
+ },
+ operator("range"),
+ ),
+ ).toEqual({
+ op: "range",
+ field: "@timestamp",
+ gte: "now-1h",
+ lte: "now",
+ });
+
+ expect(
+ changeConditionOperator(
+ { op: "term", field: "level", value: "error", gte: "stale" },
+ operator("exists"),
+ ),
+ ).toEqual({ op: "exists", field: "level" });
+ });
+});
+
+describe("field families", () => {
+ const cases: Array<[string, string]> = [
+ ["keyword", "keyword"],
+ ["constant_keyword", "keyword"],
+ ["wildcard", "keyword"],
+ ["text", "text"],
+ ["match_only_text", "text"],
+ ["search_as_you_type", "text"],
+ ["date", "date"],
+ ["date_nanos", "date"],
+ ["long", "number"],
+ ["integer", "number"],
+ ["short", "number"],
+ ["byte", "number"],
+ ["double", "number"],
+ ["float", "number"],
+ ["half_float", "number"],
+ ["scaled_float", "number"],
+ ["unsigned_long", "number"],
+ ["boolean", "boolean"],
+ ["ip", "ip"],
+ ["ip_range", "ip"],
+ ["nested", "nested"],
+ ["object", "object"],
+ ["flattened", "object"],
+ ["geo_point", "any"],
+ ["", "any"],
+ ];
+ it.each(cases)("reduces %s to the %s family", (dataType, family) => {
+ expect(fieldFamily(field({ name: "f", dataType }))).toBe(family);
+ });
+
+ it("takes the first mapped type when a field carries several", () => {
+ expect(fieldFamily(field({ name: "f", types: ["keyword", "text"] }))).toBe("keyword");
+ });
+});
+
+describe("operators offered per field", () => {
+ const operators = (mapping: Partial & { name: string }) =>
+ operatorsForField(catalog, field(mapping)).map((entry) => entry.op);
+
+ it("leads a keyword field with an exact match", () => {
+ expect(operators({ name: "level", dataType: "keyword" })).toEqual([
+ "term", "terms", "prefix", "range", "exists", "query_string", "match",
+ ]);
+ });
+
+ // A text field is analyzed, so term/prefix rarely do what an author expects.
+ // They stay available, but behind the advanced flag.
+ it("leads a text field with match and demotes the exact operators", () => {
+ const offered = operatorsForField(catalog, field({ name: "message", dataType: "text" }));
+ expect(offered.map((entry) => entry.op)).toEqual([
+ "match", "exists", "query_string", "term", "terms", "prefix",
+ ]);
+ expect(offered.find((entry) => entry.op === "term")?.advanced).toBe(true);
+ expect(offered.find((entry) => entry.op === "match")?.advanced).toBeFalsy();
+ });
+
+ it("leads a date field with a range", () => {
+ expect(operators({ name: "@timestamp", dataType: "date" })[0]).toBe("range");
+ });
+
+ it("leads a number field with a range and omits the analyzed operators", () => {
+ const offered = operators({ name: "duration", dataType: "long" });
+ expect(offered[0]).toBe("range");
+ expect(offered).not.toContain("match");
+ expect(offered).not.toContain("prefix");
+ });
+
+ it("offers a nested field a nested group rather than a leaf", () => {
+ expect(operators({ name: "spans", dataType: "nested" })).toEqual(["nested", "exists"]);
+ });
+
+ // An unsearchable field can only be tested for presence; offering anything
+ // else would build a query the backend silently returns nothing for.
+ it("offers an unsearchable field only exists", () => {
+ expect(operators({ name: "blob", dataType: "keyword", searchable: false })).toEqual([
+ "exists",
+ ]);
+ });
+
+ it("falls back to the type-independent operators for an unknown type", () => {
+ expect(operators({ name: "point", dataType: "geo_point" })).toEqual([
+ "exists", "query_string",
+ ]);
+ });
+
+ it("offers every operator when no field is selected yet", () => {
+ expect(operatorsForField(catalog, undefined).map((entry) => entry.op)).toEqual(
+ catalog.map((entry) => entry.op),
+ );
+ });
+});
+
+describe("field warnings", () => {
+ it("names every mapped type of a conflicting field", () => {
+ expect(
+ fieldWarning(field({ name: "code", conflicting: true, types: ["keyword", "long"] })),
+ ).toBe("code is mapped as keyword and long across indexes");
+ });
+
+ it("explains why an unsearchable field is limited", () => {
+ expect(fieldWarning(field({ name: "blob", dataType: "binary", searchable: false }))).toBe(
+ "blob is not searchable, so only exists applies",
+ );
+ });
+
+ it("stays quiet about an ordinary field", () => {
+ expect(fieldWarning(field({ name: "level", dataType: "keyword" }))).toBeUndefined();
+ });
+});
+
+describe("sortable fields", () => {
+ it("keeps the aggregatable fields and always offers _score and _doc", () => {
+ expect(
+ sortableFields([
+ field({ name: "@timestamp", dataType: "date" }),
+ field({ name: "message", dataType: "text", aggregatable: false }),
+ field({ name: "level", dataType: "keyword" }),
+ ]),
+ ).toEqual(["@timestamp", "level", "_score", "_doc"]);
+ });
+});
+
+describe("qualifiers", () => {
+ const names = ["analyzer", "caseInsensitive", "scoreMode", "boost"];
+ const restrictions = {
+ analyzer: ["match", "match_phrase"],
+ caseInsensitive: ["term", "prefix"],
+ scoreMode: ["nested"],
+ };
+
+ it("offers only the qualifiers the operator emits", () => {
+ expect(qualifiersForOperator({ names, restrictions, op: "match" })).toEqual([
+ "analyzer",
+ "boost",
+ ]);
+ expect(qualifiersForOperator({ names, restrictions, op: "nested" })).toEqual([
+ "scoreMode",
+ "boost",
+ ]);
+ });
+
+ // boost is absent from the table because the compiler accepts it everywhere,
+ // so an unlisted qualifier has to stay offered rather than disappear.
+ it("keeps an unrestricted qualifier for every operator", () => {
+ for (const op of ["match", "term", "nested", "range"]) {
+ expect(qualifiersForOperator({ names, restrictions, op })).toContain("boost");
+ }
+ });
+
+ it("offers everything when the schema carried no table", () => {
+ expect(qualifiersForOperator({ names, op: "match" })).toEqual(names);
+ });
+});
+
+describe("catalog extraction", () => {
+ it("reads the catalog off the search property of the options schema", () => {
+ expect(
+ operatorCatalogFromSchema({
+ properties: { search: { "x-es-operators": catalog } },
+ }),
+ ).toEqual(catalog);
+ });
+
+ it("returns nothing when the schema carries no catalog", () => {
+ expect(operatorCatalogFromSchema({ properties: { index: { type: "string" } } })).toEqual([]);
+ expect(operatorCatalogFromSchema(undefined)).toEqual([]);
+ });
+});
+
+describe("builder vocabulary", () => {
+ // The shape query/schema/search_spec.go emits, trimmed to what is read here.
+ const schema = {
+ properties: {
+ search: {
+ "x-es-operators": catalog,
+ "x-es-occurs": ["filter", "must", "should", "must_not"],
+ "x-es-qualifiers": { analyzer: ["match"], scoreMode: ["nested"] },
+ properties: {
+ query: {
+ properties: {
+ op: { type: "string" },
+ occur: { type: "string" },
+ field: { type: "string" },
+ conditions: { type: "array" },
+ analyzer: { type: "string", title: "Analyzer" },
+ boost: { type: "number", title: "Boost" },
+ scoreMode: { type: "string", title: "Score mode", enum: ["avg", "none"] },
+ },
+ },
+ sort: {
+ items: { properties: { order: { type: "string", enum: ["asc", "desc"] } } },
+ },
+ },
+ },
+ },
+ };
+
+ // A qualifier is whatever the condition schema carries beyond the structural
+ // keys, so a new one in Go reaches the advanced editor untouched here.
+ it("separates the advanced qualifiers from the structural condition keys", () => {
+ const vocabulary = esBuilderVocabulary(schema);
+ expect(vocabulary.qualifierNames).toEqual(["analyzer", "boost", "scoreMode"]);
+ expect(vocabulary.qualifiers.scoreMode).toEqual({
+ type: "string",
+ title: "Score mode",
+ enum: ["avg", "none"],
+ });
+ });
+
+ it("carries the clauses, the restriction table and the sort orders", () => {
+ const vocabulary = esBuilderVocabulary(schema);
+ expect(vocabulary.occurs).toEqual(["filter", "must", "should", "must_not"]);
+ expect(vocabulary.qualifierRestrictions).toEqual({
+ analyzer: ["match"],
+ scoreMode: ["nested"],
+ });
+ expect(vocabulary.sortOrders).toEqual(["asc", "desc"]);
+ expect(vocabulary.catalog).toEqual(catalog);
+ });
+
+ it("stays empty for a schema that describes no search", () => {
+ expect(esBuilderVocabulary({ properties: { index: { type: "string" } } })).toEqual({
+ catalog: [],
+ occurs: [],
+ qualifierNames: [],
+ qualifiers: {},
+ sortOrders: [],
+ });
+ });
+});
diff --git a/packages/ui/src/profiles/esQueryOperators.ts b/packages/ui/src/profiles/esQueryOperators.ts
new file mode 100644
index 00000000..ac172190
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryOperators.ts
@@ -0,0 +1,284 @@
+/**
+ * Which operators a field accepts. The operator vocabulary itself comes from
+ * the schema (`x-es-operators`, emitted from Go's esdsl.Catalog), so the only
+ * knowledge owned here is how a mapping type reduces to a family and how the
+ * resulting operators are ordered for an author.
+ */
+
+import {
+ defaultOperatorForFamily,
+ type EsCondition,
+} from "./esQueryBuilderModel";
+
+/** One entry of x-es-operators, keyed exactly as esdsl.OperatorInfo marshals. */
+export type EsOperatorInfo = {
+ op: string;
+ label: string;
+ arity: "none" | "single" | "multiple" | "range" | "group";
+ needsField?: boolean;
+ acceptsFields?: boolean;
+ fieldTypes: string[];
+ analyzed?: boolean;
+ group?: boolean;
+};
+
+export function changeConditionOperator(
+ condition: EsCondition,
+ next: EsOperatorInfo,
+): EsCondition {
+ const { value, values, gt, gte, lt, lte, conditions, ...rest } = condition;
+ const changed: EsCondition = { ...rest, op: next.op };
+
+ if (next.arity === "single") {
+ const operand = value !== undefined
+ ? value
+ : values?.length === 1
+ ? values[0]
+ : undefined;
+ return operand === undefined ? changed : { ...changed, value: operand };
+ }
+ if (next.arity === "multiple") {
+ const operands = values?.length
+ ? values
+ : value === undefined
+ ? []
+ : [value];
+ return operands.length === 0 ? changed : { ...changed, values: operands };
+ }
+ if (next.arity === "range") {
+ return {
+ ...changed,
+ ...(gt !== undefined ? { gt } : {}),
+ ...(gte !== undefined ? { gte } : {}),
+ ...(lt !== undefined ? { lt } : {}),
+ ...(lte !== undefined ? { lte } : {}),
+ };
+ }
+ if (next.arity === "group") {
+ return { ...changed, conditions: conditions ?? [] };
+ }
+ return changed;
+}
+
+/** A field as _field_caps reports it, via the browser inspection response. */
+export type EsFieldMapping = {
+ name: string;
+ dataType?: string;
+ types?: string[];
+ searchable?: boolean;
+ aggregatable?: boolean;
+ conflicting?: boolean;
+};
+
+/** An offered operator. `advanced` marks one that fights the field's analysis. */
+export type OfferedOperator = EsOperatorInfo & { advanced?: boolean };
+
+const families: Record = {
+ keyword: "keyword",
+ constant_keyword: "keyword",
+ wildcard: "keyword",
+ text: "text",
+ match_only_text: "text",
+ search_as_you_type: "text",
+ date: "date",
+ date_nanos: "date",
+ long: "number",
+ integer: "number",
+ short: "number",
+ byte: "number",
+ double: "number",
+ float: "number",
+ half_float: "number",
+ scaled_float: "number",
+ unsigned_long: "number",
+ boolean: "boolean",
+ ip: "ip",
+ ip_range: "ip",
+ nested: "nested",
+ object: "object",
+ flattened: "object",
+};
+
+// Families whose values are run through an analyzer at index time, so an exact
+// operator on them matches tokens rather than the stored text.
+const analyzedFamilies = new Set(["text"]);
+
+// Structural families hold other fields rather than a value: they are descended
+// into or tested for presence, never matched against.
+const structuralFamilies = new Set(["nested", "object"]);
+
+export function fieldFamily(field: EsFieldMapping | undefined): string {
+ const mapped = field?.dataType || field?.types?.[0] || "";
+ return families[mapped] ?? "any";
+}
+
+/**
+ * operatorsForField ranks the applicable operators: the family's default first,
+ * then the rest that suit it, then the type-independent ones, and finally the
+ * ones that fight the field's analysis — those carry `advanced`.
+ */
+export function operatorsForField(
+ catalog: EsOperatorInfo[],
+ field: EsFieldMapping | undefined,
+): OfferedOperator[] {
+ if (!field) return catalog.map((entry) => ({ ...entry }));
+ if (field.searchable === false) {
+ return catalog.filter((entry) => entry.op === "exists").map((entry) => ({ ...entry }));
+ }
+ const family = fieldFamily(field);
+ if (structuralFamilies.has(family)) {
+ return catalog
+ .filter((entry) => entry.op === "exists" || entry.fieldTypes.includes(family))
+ .sort((left, right) => Number(left.op === "exists") - Number(right.op === "exists"))
+ .map((entry) => ({ ...entry }));
+ }
+
+ const analyzed = analyzedFamilies.has(family);
+ const preferred = defaultOperatorForFamily(family);
+ const ranked = catalog.flatMap((entry, position) => {
+ if (entry.group) return [];
+ const direct = entry.fieldTypes.includes(family);
+ const generic = entry.fieldTypes.includes("any");
+ if (!direct && !generic) return [];
+ if (direct && entry.op === preferred) return [{ entry, rank: 0, position }];
+ if (direct && Boolean(entry.analyzed) !== analyzed) {
+ return [{ entry: { ...entry, advanced: true }, rank: 3, position }];
+ }
+ return [{ entry, rank: direct ? 1 : 2, position }];
+ });
+ return ranked
+ .sort((left, right) => left.rank - right.rank || left.position - right.position)
+ .map(({ entry }) => ({ ...entry }));
+}
+
+/**
+ * fieldWarning explains a field the author cannot query the way they expect. A
+ * conflicting field is still offered — hiding it would silently drop a field
+ * that works on most of the matched indexes.
+ */
+export function fieldWarning(field: EsFieldMapping): string | undefined {
+ if (field.conflicting) {
+ const types = field.types ?? (field.dataType ? [field.dataType] : []);
+ return `${field.name} is mapped as ${joinWithAnd(types)} across indexes`;
+ }
+ if (field.searchable === false) {
+ return `${field.name} is not searchable, so only exists applies`;
+ }
+ return undefined;
+}
+
+/** sortableFields lists what can order the hits: doc values, _score and _doc. */
+export function sortableFields(fields: EsFieldMapping[]): string[] {
+ return [
+ ...fields.filter((field) => field.aggregatable !== false).map((field) => field.name),
+ "_score",
+ "_doc",
+ ];
+}
+
+/**
+ * qualifiersForOperator narrows the advanced settings to the ones the operator
+ * emits. `restrictions` is the schema's x-es-qualifiers table, which lists only
+ * the qualifiers the compiler restricts — a name it omits applies everywhere.
+ */
+export function qualifiersForOperator(options: {
+ names: string[];
+ restrictions?: Record;
+ op: string;
+}): string[] {
+ const { names, restrictions = {}, op } = options;
+ return names.filter((name) => !restrictions[name] || restrictions[name].includes(op));
+}
+
+type OptionsSchema = { properties?: Record } | undefined;
+
+type SchemaNode = {
+ properties?: Record;
+ items?: SchemaNode;
+ enum?: string[];
+ "x-es-operators"?: EsOperatorInfo[];
+ "x-es-occurs"?: string[];
+ "x-es-qualifiers"?: Record;
+};
+
+function searchProperty(schema: OptionsSchema): SchemaNode | undefined {
+ return schema?.properties?.search as SchemaNode | undefined;
+}
+
+/** operatorCatalogFromSchema reads x-es-operators off the search property. */
+export function operatorCatalogFromSchema(schema: OptionsSchema): EsOperatorInfo[] {
+ return searchProperty(schema)?.["x-es-operators"] ?? [];
+}
+
+/** esQualifiersFromSchema is the same read for the qualifier-to-operator table. */
+export function esQualifiersFromSchema(
+ schema: OptionsSchema,
+): Record | undefined {
+ return searchProperty(schema)?.["x-es-qualifiers"];
+}
+
+/** One advanced qualifier, as the condition schema describes it. */
+export type EsQualifierSchema = {
+ title?: string;
+ description?: string;
+ type?: string;
+ enum?: string[];
+ default?: unknown;
+};
+
+/**
+ * Everything about a search that Go owns: the operator catalog, the bool
+ * clauses, the advanced qualifiers and the sort orders. The builder reads all of
+ * it off the schema, so adding a qualifier or an operator in esdsl reaches the
+ * editor without a frontend change.
+ */
+export type EsBuilderVocabulary = {
+ catalog: EsOperatorInfo[];
+ occurs: string[];
+ qualifierNames: string[];
+ qualifierRestrictions?: Record;
+ qualifiers: Record;
+ sortOrders: string[];
+};
+
+// The condition properties that carry structure rather than an advanced
+// setting. Whatever the schema holds beyond these is a qualifier.
+const structuralConditionKeys = new Set([
+ "op",
+ "occur",
+ "field",
+ "fields",
+ "value",
+ "values",
+ "gt",
+ "gte",
+ "lt",
+ "lte",
+ "optional",
+ "when",
+ "conditions",
+]);
+
+export function esBuilderVocabulary(schema: OptionsSchema): EsBuilderVocabulary {
+ const search = searchProperty(schema);
+ const conditionProperties = search?.properties?.query?.properties ?? {};
+ const qualifiers: Record = {};
+ for (const [name, property] of Object.entries(conditionProperties)) {
+ if (structuralConditionKeys.has(name)) continue;
+ qualifiers[name] = property as EsQualifierSchema;
+ }
+ const restrictions = esQualifiersFromSchema(schema);
+ return {
+ catalog: operatorCatalogFromSchema(schema),
+ occurs: search?.["x-es-occurs"] ?? [],
+ qualifierNames: Object.keys(qualifiers),
+ ...(restrictions ? { qualifierRestrictions: restrictions } : {}),
+ qualifiers,
+ sortOrders: search?.properties?.sort?.items?.properties?.order?.enum ?? [],
+ };
+}
+
+function joinWithAnd(values: string[]): string {
+ if (values.length < 2) return values.join("");
+ return `${values.slice(0, -1).join(", ")} and ${values[values.length - 1]}`;
+}
diff --git a/packages/ui/src/profiles/esQueryOutputEditor.tsx b/packages/ui/src/profiles/esQueryOutputEditor.tsx
new file mode 100644
index 00000000..ac59fce5
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryOutputEditor.tsx
@@ -0,0 +1,154 @@
+/**
+ * What a matching document comes back as: where the hits start, which _source
+ * fields travel, and whether the backend counts past its default. How many hits
+ * come back is the query's Limit, edited next to the filters — one row cap, so
+ * that it cannot disagree with itself across the form and the raw DSL.
+ */
+
+import { InputField } from "../components/InputField";
+import { useState } from "react";
+import type { EsSearch } from "./esQueryBuilderModel";
+import type { Patch } from "./profileWizardModel";
+import { parseCount, pruneEmpty } from "./esQueryOutputModel";
+
+export function EsQueryOutputEditor({
+ search,
+ onChange,
+}: {
+ search: EsSearch;
+ onChange: (patch: Patch) => void;
+}) {
+ const source = search.source ?? {};
+ const total = search.trackTotalHits ?? {};
+ const setSource = (patch: Partial>) =>
+ onChange({ source: pruneEmpty({ ...source, ...patch }) });
+ const setTotal = (patch: Partial>) =>
+ onChange({ trackTotalHits: pruneEmpty({ ...total, ...patch }) });
+
+ return (
+
+ );
+}
+
+/**
+ * A list of _source field patterns. They are patterns rather than field names —
+ * `user.*` is the point of them — so this stays free text rather than a picker.
+ */
+function PatternList({
+ label,
+ values,
+ onChange,
+}: {
+ label: string;
+ values: string[];
+ onChange: (values: string[]) => void;
+}) {
+ const [draft, setDraft] = useState("");
+ const commit = () => {
+ const parsed = draft
+ .split(",")
+ .map((entry) => entry.trim())
+ .filter(Boolean);
+ if (!parsed.length) return;
+ onChange([...values, ...parsed]);
+ setDraft("");
+ };
+ return (
+
+ {label}
+ {values.map((value, index) => (
+
+ {value}
+
+ onChange(values.filter((_entry, position) => position !== index))
+ }
+ >
+ ×
+
+
+ ))}
+ {
+ if (event.key !== "Enter" && event.key !== ",") return;
+ event.preventDefault();
+ commit();
+ }}
+ onBlur={commit}
+ />
+
+ );
+}
diff --git a/packages/ui/src/profiles/esQueryOutputEditors.test.tsx b/packages/ui/src/profiles/esQueryOutputEditors.test.tsx
new file mode 100644
index 00000000..b7b19365
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryOutputEditors.test.tsx
@@ -0,0 +1,171 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { EsQuerySortEditor } from "./esQuerySortEditor";
+import { moveSortEntry } from "./esQuerySortModel";
+import { EsQueryOutputEditor } from "./esQueryOutputEditor";
+import { parseCount, pruneEmpty } from "./esQueryOutputModel";
+import type { EsSearch, EsSortBy } from "./esQueryBuilderModel";
+import type { EsFieldMapping } from "./esQueryOperators";
+
+const fields: EsFieldMapping[] = [
+ { name: "@timestamp", dataType: "date", searchable: true, aggregatable: true },
+ { name: "message", dataType: "text", searchable: true, aggregatable: false },
+ { name: "level", dataType: "keyword", searchable: true, aggregatable: true },
+];
+
+const renderSort = (sort: EsSortBy[]) =>
+ renderToStaticMarkup(
+ undefined}
+ />,
+ );
+
+/** The opening tag of the element carrying `ariaLabel`, attributes and all. */
+const openingTag = (html: string, ariaLabel: string): string => {
+ const at = html.indexOf(`aria-label="${ariaLabel}"`);
+ expect(at, `no element labelled ${ariaLabel}`).toBeGreaterThan(-1);
+ return html.slice(at, html.indexOf(">", at));
+};
+
+const renderOutput = (search: EsSearch) =>
+ renderToStaticMarkup(
+ undefined} />,
+ );
+
+describe("reordering sort entries", () => {
+ const sort: EsSortBy[] = [
+ { field: "@timestamp" },
+ { field: "level" },
+ { field: "_score" },
+ ];
+
+ it("swaps an entry with the one before it", () => {
+ expect(moveSortEntry(sort, 1, -1).map((entry) => entry.field)).toEqual([
+ "level",
+ "@timestamp",
+ "_score",
+ ]);
+ });
+
+ it("swaps an entry with the one after it", () => {
+ expect(moveSortEntry(sort, 0, 1).map((entry) => entry.field)).toEqual([
+ "level",
+ "@timestamp",
+ "_score",
+ ]);
+ });
+
+ // Wrapping would silently make the first tie-break the last, which is the
+ // opposite of what a click on a disabled-looking arrow should do.
+ it("clamps at both ends rather than wrapping", () => {
+ expect(moveSortEntry(sort, 0, -1)).toBe(sort);
+ expect(moveSortEntry(sort, 2, 1)).toBe(sort);
+ });
+
+ it("leaves the entries it did not move alone", () => {
+ expect(moveSortEntry(sort, 1, -1)[2]).toBe(sort[2]);
+ });
+});
+
+describe("the sort editor", () => {
+ it("renders one field and order control per sort entry", () => {
+ const html = renderSort([
+ { field: "@timestamp", order: "desc" },
+ { field: "level" },
+ ]);
+ expect(html.match(/aria-label="Sort field"/g)).toHaveLength(2);
+ expect(html).toContain('value="@timestamp"');
+ expect(html).toContain('desc ');
+ });
+
+ it("says plainly when nothing sorts the hits", () => {
+ expect(renderSort([])).toContain("Unsorted");
+ expect(renderSort([{ field: "level" }])).not.toContain("Unsorted");
+ });
+
+ it("names each move control after the field it moves", () => {
+ const html = renderSort([{ field: "@timestamp" }, { field: "level" }]);
+ expect(html).toContain('aria-label="Move @timestamp later"');
+ expect(html).toContain('aria-label="Move level earlier"');
+ expect(html).toContain('aria-label="Remove level"');
+ });
+
+ it("disables the move that would run off either end", () => {
+ const html = renderSort([{ field: "@timestamp" }, { field: "level" }]);
+ // The bare word also appears in Tailwind's disabled: variants, so this has
+ // to look for the attribute itself.
+ expect(openingTag(html, "Move @timestamp earlier")).toContain('disabled=""');
+ expect(openingTag(html, "Move level later")).toContain('disabled=""');
+ expect(openingTag(html, "Move @timestamp later")).not.toContain('disabled=""');
+ expect(openingTag(html, "Move level earlier")).not.toContain('disabled=""');
+ });
+});
+
+describe("pruning an empty sub-object", () => {
+ it("keeps a sub-object that still says something", () => {
+ expect(pruneEmpty({ enabled: false })).toEqual({ enabled: false });
+ expect(pruneEmpty({ includes: ["user.*"] })).toEqual({
+ includes: ["user.*"],
+ });
+ });
+
+ // Storing `{}` would leave a key the compiler has to ignore, so clearing the
+ // last field has to clear the object with it.
+ it("drops one whose every field was cleared", () => {
+ expect(pruneEmpty({ enabled: undefined, includes: [] })).toBeUndefined();
+ expect(pruneEmpty({})).toBeUndefined();
+ });
+});
+
+describe("reading a count", () => {
+ it.each([
+ ["25", 25],
+ ["0", 0],
+ ])("accepts %s as %i", (raw, expected) => {
+ expect(parseCount(raw)).toBe(expected);
+ });
+
+ it.each(["", " ", "-1", "1.5", "many"])("treats %j as unset", (raw) => {
+ expect(parseCount(raw)).toBeUndefined();
+ });
+});
+
+describe("the output editor", () => {
+ it("shows where the hits start and the _source controls", () => {
+ const html = renderOutput({ from: 20 });
+ expect(html).toContain('aria-label="From"');
+ expect(html).toContain('value="20"');
+ expect(html).toContain('aria-label="Add includes pattern"');
+ expect(html).toContain('aria-label="Add excludes pattern"');
+ });
+
+ // How many rows come back is the query's Limit, edited beside the filters.
+ // A second control here would be a row cap that can disagree with the one the
+ // raw query also honours.
+ it("leaves the row count to the query's own limit", () => {
+ expect(renderOutput({ size: 100 })).not.toContain('aria-label="Size"');
+ });
+
+ it("renders each stored _source pattern as a removable chip", () => {
+ const html = renderOutput({ source: { includes: ["user.*", "@timestamp"] } });
+ expect(html.match(/es-pattern-chip/g)).toHaveLength(2);
+ expect(html).toContain('aria-label="Remove user.*"');
+ });
+
+ // With _source off there is nothing to include or exclude, so the pattern
+ // lists would only collect values the backend never reads.
+ it("hides the pattern lists once _source is turned off", () => {
+ const html = renderOutput({ source: { enabled: false } });
+ expect(html).not.toContain('aria-label="Add includes pattern"');
+ });
+
+ it("asks for a threshold only while total hits are tracked", () => {
+ expect(renderOutput({})).not.toContain('aria-label="Total hits threshold"');
+ expect(renderOutput({ trackTotalHits: { enabled: true } })).toContain(
+ 'aria-label="Total hits threshold"',
+ );
+ });
+});
diff --git a/packages/ui/src/profiles/esQueryOutputModel.ts b/packages/ui/src/profiles/esQueryOutputModel.ts
new file mode 100644
index 00000000..32d4919e
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryOutputModel.ts
@@ -0,0 +1,25 @@
+/**
+ * What a matching document comes back as: where the hits start, which _source
+ * fields travel, and whether the backend counts past its default. How many hits
+ * come back is the query's Limit, edited next to the filters — one row cap, so
+ * that it cannot disagree with itself across the form and the raw DSL.
+ */
+
+
+/**
+ * pruneEmpty drops a sub-object that says nothing, so clearing the last field of
+ * `source` removes `source` rather than storing `{}` the compiler must ignore.
+ */
+export function pruneEmpty(value: T): T | undefined {
+ const said = Object.values(value).some((entry) =>
+ Array.isArray(entry) ? entry.length > 0 : entry !== undefined && entry !== null,
+ );
+ return said ? value : undefined;
+}
+
+/** parseCount reads a non-negative integer, treating anything else as unset. */
+export function parseCount(raw: string): number | undefined {
+ if (raw.trim() === "") return undefined;
+ const parsed = Number(raw);
+ return Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined;
+}
diff --git a/packages/ui/src/profiles/esQueryPreview.tsx b/packages/ui/src/profiles/esQueryPreview.tsx
new file mode 100644
index 00000000..d5dc8974
--- /dev/null
+++ b/packages/ui/src/profiles/esQueryPreview.tsx
@@ -0,0 +1,45 @@
+/**
+ * The DSL a specification compiles to. The server compiles it — the same code
+ * path a query runs through — so the preview is the query, not a re-derivation
+ * of it that could drift.
+ */
+
+import type { EsCompilation } from "./esQueryCompile";
+
+export function EsQueryPreview({
+ compilation,
+ className
+}: {
+ compilation: EsCompilation;
+ className?: string;
+}) {
+ const { query, size, from, error, loading } = compilation;
+ return (
+
+
+ Compiled DSL
+ {size === undefined ? null : (
+
+ size {size}
+ {from ? ` · from ${from}` : ""}
+
+ )}
+ {loading ? (
+ compiling…
+ ) : null}
+
+ {error ? (
+
+ {error}
+
+ ) : (
+
+ {query}
+
+ )}
+
+ );
+}
diff --git a/packages/ui/src/profiles/esQuerySortEditor.tsx b/packages/ui/src/profiles/esQuerySortEditor.tsx
new file mode 100644
index 00000000..aaed5550
--- /dev/null
+++ b/packages/ui/src/profiles/esQuerySortEditor.tsx
@@ -0,0 +1,136 @@
+/**
+ * Multi-field sort. The order of the entries is the tie-break order the backend
+ * applies, so moving an entry is an edit in its own right rather than cosmetic.
+ */
+
+import { Combobox } from "../components/Combobox";
+import { IconButton } from "../components/IconButton";
+import { InputField } from "../components/InputField";
+import { Button } from "../components/button";
+import { Select } from "../components/select";
+import { UiAdd, UiArrowDown, UiArrowUp, UiTrash } from "../icons";
+import type { EsSortBy } from "./esQueryBuilderModel";
+import { applyPatch, type Patch } from "./profileWizardModel";
+import { sortableFields, type EsFieldMapping } from "./esQueryOperators";
+import { moveSortEntry } from "./esQuerySortModel";
+
+export function EsQuerySortEditor({
+ sort,
+ fields,
+ orders,
+ onChange,
+}: {
+ sort: EsSortBy[];
+ fields: EsFieldMapping[];
+ orders: string[];
+ onChange: (sort: EsSortBy[]) => void;
+}) {
+ const options = sortableFields(fields).map((name) => ({
+ value: name,
+ label: name,
+ }));
+ const set = (index: number, patch: Patch) =>
+ onChange(
+ sort.map((entry, position) =>
+ position === index ? applyPatch(entry, patch) : entry,
+ ),
+ );
+ const text = (value: string | undefined) => value ?? "";
+
+ return (
+
+
+ Sort
+
+ onChange([
+ ...sort,
+ // An empty vocabulary leaves the order unset, which is the same
+ // as the backend's default — not an entry with order: undefined.
+ { field: "", ...(orders[0] ? { order: orders[0] } : {}) },
+ ])
+ }
+ >
+
+
+ {sort.length === 0 ? (
+
+ Unsorted — hits come back in the backend's own order.
+
+ ) : null}
+ {sort.map((entry, index) => (
+
+ set(index, { field: next })}
+ options={options}
+ placeholder="Field…"
+ allowCustomValue
+ />
+
+ ({ value: order, label: order })),
+ ]}
+ onChange={(event) =>
+ set(index, { order: event.target.value || undefined })
+ }
+ />
+
+ set(index, { mode: next || undefined })}
+ />
+ set(index, { missing: next || undefined })}
+ />
+ set(index, { unmappedType: next || undefined })}
+ />
+ onChange(moveSortEntry(sort, index, -1))}
+ />
+ onChange(moveSortEntry(sort, index, 1))}
+ />
+
+ onChange(sort.filter((_entry, position) => position !== index))
+ }
+ />
+
+ ))}
+
+ );
+}
diff --git a/packages/ui/src/profiles/esQuerySortModel.ts b/packages/ui/src/profiles/esQuerySortModel.ts
new file mode 100644
index 00000000..8357f60a
--- /dev/null
+++ b/packages/ui/src/profiles/esQuerySortModel.ts
@@ -0,0 +1,21 @@
+/**
+ * Multi-field sort. The order of the entries is the tie-break order the backend
+ * applies, so moving an entry is an edit in its own right rather than cosmetic.
+ */
+
+import type { EsSortBy } from "./esQueryBuilderModel";
+
+/** moveSortEntry shifts one entry, clamping at the ends rather than wrapping. */
+export function moveSortEntry(
+ sort: EsSortBy[],
+ index: number,
+ delta: number,
+): EsSortBy[] {
+ const target = index + delta;
+ if (target < 0 || target >= sort.length) return sort;
+ const moved = [...sort];
+ const [entry] = moved.splice(index, 1);
+ if (!entry) throw new Error(`sort entry ${index} does not exist`);
+ moved.splice(target, 0, entry);
+ return moved;
+}
diff --git a/packages/ui/src/profiles/esValueCombobox.test.tsx b/packages/ui/src/profiles/esValueCombobox.test.tsx
new file mode 100644
index 00000000..b55d66fa
--- /dev/null
+++ b/packages/ui/src/profiles/esValueCombobox.test.tsx
@@ -0,0 +1,52 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderToStaticMarkup } from "react-dom/server";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const comboboxCalls = vi.hoisted(() => [] as Record[]);
+
+vi.mock("../components/Combobox", () => ({
+ Combobox: (props: Record) => {
+ comboboxCalls.push(props);
+ return
+ ({ values: [], total: 0, scoped: true }),
+ }}
+ values={["payments"]}
+ onChange={onChange}
+ />
+ ,
+ );
+
+ expect(comboboxCalls).toHaveLength(1);
+ expect(comboboxCalls[0]).toMatchObject({
+ multiple: true,
+ variant: "tags",
+ allowCustomValue: true,
+ value: ["payments"],
+ });
+
+ const change = comboboxCalls[0]?.onChange as
+ | ((next: string[]) => void)
+ | undefined;
+ expect(change).toBeDefined();
+ change?.(["payments", "custom-service"]);
+ expect(onChange).toHaveBeenCalledWith(["payments", "custom-service"]);
+ });
+});
diff --git a/packages/ui/src/profiles/esValueCombobox.tsx b/packages/ui/src/profiles/esValueCombobox.tsx
new file mode 100644
index 00000000..e963e0c3
--- /dev/null
+++ b/packages/ui/src/profiles/esValueCombobox.tsx
@@ -0,0 +1,110 @@
+/**
+ * The operand controls backed by a field's real values. Typing narrows the
+ * terms aggregation server-side rather than filtering a fetched page, so a
+ * field with thousands of values stays usable; a value outside the returned
+ * window is still typeable, which is what `allowCustomValue` stands for.
+ */
+
+import { Combobox } from "../components/Combobox";
+import type { ComboboxOption } from "../components/Combobox";
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import { useState } from "react";
+import type { FieldValuesQuery, FieldValuesResult } from "./esFieldValues";
+
+function useFieldValues(lookup: FieldValuesQuery) {
+ const [query, setQuery] = useState("");
+ const result = useQuery({
+ queryKey: ["es-field-values", lookup.key, query],
+ queryFn: () => lookup.fetch(query),
+ placeholderData: keepPreviousData,
+ staleTime: 30_000,
+ retry: 0,
+ });
+ return { ...result, onSearch: setQuery };
+}
+
+function valueOptions(result: FieldValuesResult | undefined): ComboboxOption[] {
+ return (result?.values ?? []).map((entry) => ({
+ value: entry.value,
+ label: entry.value,
+ title: `${entry.count.toLocaleString()} documents`,
+ }));
+}
+
+/**
+ * The summary explains what the list is a window onto: how much of the field's
+ * cardinality is shown, and whether the rest of the query narrowed it.
+ */
+function valueSummary(
+ result: FieldValuesResult | undefined,
+ error: Error | null,
+): string | undefined {
+ if (error) return error.message;
+ if (!result) return undefined;
+ const scope = result.scoped ? "matching current filters" : "across the index";
+ if (!result.values.length) return `no values ${scope}`;
+ return `${result.values.length} of ${result.total.toLocaleString()} · ${scope}`;
+}
+
+export function ValueCombobox({
+ id,
+ label,
+ lookup,
+ value,
+ onChange,
+}: {
+ id: string;
+ label: string;
+ lookup: FieldValuesQuery;
+ value: string;
+ onChange: (next: string) => void;
+}) {
+ const { data, error, isFetching, onSearch } = useFieldValues(lookup);
+ const summary = valueSummary(data, error as Error | null);
+ return (
+ | null {
+ if (!isRecord(profile)) return null;
+ const provider = profile.provider;
+ if (!isRecord(provider)) return null;
+ const type = typeof provider.type === "string" ? provider.type.trim() : "";
+ if (!type) return null;
+ const request: Record = {};
+ for (const key of SAMPLE_PROFILE_KEYS) {
+ if (profile[key] !== undefined) request[key] = profile[key];
+ }
+ const name = typeof profile.profile === "string" ? profile.profile.trim() : "";
+ request.profile = name || "sample";
+ return request;
+}
+
+/**
+ * The rows the picker browses: a read-only sample of `profile`.
+ *
+ * A profile that cannot be sampled — no provider yet, or a query the backend
+ * rejects — yields nothing, which leaves JSONPathField's browse button disabled
+ * and the path typed by hand rather than picked.
+ */
+export function useJsonPathSample(profile: unknown): unknown[] {
+ const request = useMemo(() => sampleRequestProfile(profile), [profile]);
+ const { data } = useQuery({
+ queryKey: ["jsonpath-sample", JSON.stringify(request)],
+ enabled: request !== null,
+ // The sample is a query against someone's backend, so it is fetched once per
+ // profile shape and reused by every column's picker rather than re-run as
+ // the form re-renders.
+ staleTime: Infinity,
+ gcTime: 5 * 60 * 1000,
+ retry: false,
+ refetchOnWindowFocus: false,
+ queryFn: async () => {
+ const result = await fetchJSON<{ rows?: Record[] }>(
+ profileApiPath("profile/sample"),
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ profile: request, params: {} }),
+ },
+ );
+ return result.rows ?? EMPTY_ROWS;
+ },
+ });
+ return data ?? EMPTY_ROWS;
+}
+
+/**
+ * Evaluates a JSONPath against one sampled row, server-side.
+ *
+ * The path has to be read by the library the query engine reads it with, or the
+ * preview would confidently disagree with the column it previews. The row goes
+ * up with the request because the caller already has it — re-running someone's
+ * backend query on every keystroke would make the preview cost real money.
+ */
+export function evaluateJsonPath(request: {
+ jsonpath: string;
+ source?: string;
+ row: unknown;
+}): Promise {
+ return fetchJSON(profileApiPath("profile/sample/jsonpath"), {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify(request),
+ });
+}
+
+// A stable identity so a component reading "nothing sampled" does not re-render
+// every parent render on a fresh [].
+const EMPTY_ROWS: unknown[] = [];
+
+// The rows the JSONPath picker browses, for the surfaces that cannot ask for
+// them themselves.
+//
+// The entity form's extension reads the profile straight off the form root and
+// samples it directly. The standalone profile editor renders its column
+// inspector far from the draft it is editing, so that page samples once here and
+// every column field reads the result — one request per editor rather than one
+// per column, and no query client needed at the leaf.
+export const JsonPathSampleRowsContext = createContext(EMPTY_ROWS);
+
+// The keys /profile/sample accepts. It decodes with DisallowUnknownFields, so
+// this is a whitelist rather than a tidy-up: one stray key and the whole request
+// is a 400.
+//
+// `columns`, `aliases` and `ignore` are left out deliberately. Those transforms
+// are the thing the author is still writing — a source column gets renamed and
+// consumed by them — and the picker has to offer the provider's own row shape,
+// not the shape a half-written profile projects out of it.
+const SAMPLE_PROFILE_KEYS = [
+ "profile",
+ "provider",
+ "query",
+ "params",
+ "imports",
+ "namespace",
+] as const;
+
+function isRecord(value: unknown): value is Record {
+ return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
diff --git a/packages/ui/src/profiles/jsonPathSampleRow.test.ts b/packages/ui/src/profiles/jsonPathSampleRow.test.ts
new file mode 100644
index 00000000..b9ebe3bb
--- /dev/null
+++ b/packages/ui/src/profiles/jsonPathSampleRow.test.ts
@@ -0,0 +1,69 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { evaluateJsonPath, sampleRequestProfile } from "./jsonPathSample";
+
+const profile = {
+ profile: "orders",
+ namespace: "default",
+ provider: { type: "sql", options: { url: "postgres://localhost/orders" } },
+ query: "SELECT payload FROM orders",
+ params: [{ name: "since", type: "string" }],
+ columns: [{ name: "email", source: "payload", jsonpath: "$.user.email" }],
+ aliases: [{ name: "user", cel: "row.payload.user" }],
+ ignore: ["payload"],
+ render: "logs",
+};
+
+describe("sampleRequestProfile", () => {
+ it("keeps only the keys the sample endpoint accepts", () => {
+ // /profile/sample decodes with DisallowUnknownFields, so anything extra —
+ // `render` here — turns the whole request into a 400.
+ expect(sampleRequestProfile(profile)).toEqual({
+ profile: "orders",
+ namespace: "default",
+ provider: { type: "sql", options: { url: "postgres://localhost/orders" } },
+ query: "SELECT payload FROM orders",
+ params: [{ name: "since", type: "string" }],
+ });
+ });
+
+ it("drops the transforms so the raw provider row is sampled", () => {
+ const request = sampleRequestProfile(profile)!;
+
+ expect(request).not.toHaveProperty("columns");
+ expect(request).not.toHaveProperty("aliases");
+ expect(request).not.toHaveProperty("ignore");
+ });
+
+ it("names an unnamed draft so the handler accepts it", () => {
+ const request = sampleRequestProfile({ ...profile, profile: " " })!;
+
+ expect(request.profile).toBe("sample");
+ });
+
+ it("declines a profile with no provider to sample", () => {
+ expect(sampleRequestProfile({ query: "SELECT 1" })).toBeNull();
+ expect(sampleRequestProfile({ provider: { type: "" }, query: "SELECT 1" })).toBeNull();
+ expect(sampleRequestProfile(undefined)).toBeNull();
+ });
+});
+
+describe("evaluateJsonPath", () => {
+ afterEach(() => vi.unstubAllGlobals());
+
+ it("sends the expression, its root and the row the caller is already holding", async () => {
+ const response = { matches: ["OPEN"], count: 1, filterField: "payload.status" };
+ const fetchMock = vi.fn(async () => new Response(JSON.stringify(response), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ }));
+ vi.stubGlobal("fetch", fetchMock);
+
+ const row = { payload: '{"status":"OPEN"}' };
+ await expect(evaluateJsonPath({ jsonpath: "$.status", source: "payload", row })).resolves.toEqual(response);
+
+ const [url, init] = fetchMock.mock.calls[0]!;
+ expect(url).toBe("/api/v1/profile/sample/jsonpath");
+ expect(init?.method).toBe("POST");
+ expect(JSON.parse(init?.body as string)).toEqual({ jsonpath: "$.status", source: "payload", row });
+ });
+});
diff --git a/packages/ui/src/profiles/jsonPathSampleRow.tsx b/packages/ui/src/profiles/jsonPathSampleRow.tsx
new file mode 100644
index 00000000..b3086d43
--- /dev/null
+++ b/packages/ui/src/profiles/jsonPathSampleRow.tsx
@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+import { JsonPathSampleRowsContext, useJsonPathSample } from "./jsonPathSample";
+
+export function JsonPathProfileProvider({
+ profile,
+ children
+}: {
+ profile: unknown;
+ children: ReactNode;
+}) {
+ const rows = useJsonPathSample(profile);
+ return (
+
+ {children}
+
+ );
+}
+
diff --git a/packages/ui/src/profiles/profileApi.ts b/packages/ui/src/profiles/profileApi.ts
new file mode 100644
index 00000000..e466f01e
--- /dev/null
+++ b/packages/ui/src/profiles/profileApi.ts
@@ -0,0 +1,80 @@
+/**
+ * Boot-time configuration: where the profile engine is mounted, and the schema
+ * that describes a profile.
+ *
+ * Both are the host's to supply. The components talk to commons-db's profile
+ * service — sampling a draft, evaluating a JSONPath against a sampled row,
+ * browsing a connection's catalog — and every host mounts that service
+ * somewhere; a library that hardcodes one host's prefix is broken for the next.
+ * The schema is generated from commons-db's Go types, so it ships with the
+ * server, not with this package: vendoring a copy here would silently drift
+ * from the source of truth the server validates against.
+ *
+ * This is module state rather than a React context on purpose: both values are
+ * one per application, fixed before the first render, and read from plain
+ * functions (browserBaseUrl, profileSchemaProjection) as well as components.
+ * Threading a context through the whole tree would buy nothing a single
+ * boot-time call does not.
+ */
+
+import type { JsonSchemaObject } from "../components/json-schema-form-types";
+import { stripTrailingSlashes } from "../lib/string";
+
+/** ProfileSchema is commons-db's profile.json, with its $defs preserved. */
+export type ProfileSchema = JsonSchemaObject & {
+ $defs?: Record;
+};
+
+const DEFAULT_BASE = "/api/v1";
+
+let base = DEFAULT_BASE;
+let schema: ProfileSchema | null = null;
+
+/**
+ * configureProfiles points the components at a mount and gives them the profile
+ * schema. Call it once at startup, before rendering.
+ *
+ * basePath defaults to /api/v1 and may be omitted by a host that mounts there.
+ * schema has no default: the editor cannot describe a profile it has no schema
+ * for, and inventing one would disagree with the server that validates it.
+ */
+export function configureProfiles(options: { basePath?: string; schema: ProfileSchema }): void {
+ if (options.basePath !== undefined) {
+ const trimmed = stripTrailingSlashes(options.basePath.trim());
+ if (!trimmed.startsWith("/")) {
+ throw new Error(
+ `profile API basePath must start with "/", got ${JSON.stringify(options.basePath)}`,
+ );
+ }
+ base = trimmed;
+ }
+ schema = options.schema;
+}
+
+/** profileApiBase is the configured mount point, without a trailing slash. */
+export function profileApiBase(): string {
+ return base;
+}
+
+/**
+ * profileApiPath joins a service-relative path onto the mount point, e.g.
+ * profileApiPath("profile/sample") -> "/api/v1/profile/sample".
+ */
+export function profileApiPath(suffix: string): string {
+ return `${base}/${suffix.replace(/^\/+/, "")}`;
+}
+
+/**
+ * profileSchema is the configured schema. It throws rather than returning an
+ * empty document: a form rendered from a missing schema shows no fields at all,
+ * which reads as "this profile has nothing to configure" instead of as the
+ * setup error it is.
+ */
+export function profileSchema(): ProfileSchema {
+ if (!schema) {
+ throw new Error(
+ "profile schema is not configured — call configureProfiles({ schema }) before rendering the profile editor",
+ );
+ }
+ return schema;
+}
diff --git a/packages/ui/src/profiles/profileBuilder.test.ts b/packages/ui/src/profiles/profileBuilder.test.ts
new file mode 100644
index 00000000..3ef19aed
--- /dev/null
+++ b/packages/ui/src/profiles/profileBuilder.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { profileBuilderModalClassName } from "./profileBuilderWorkspace";
+import { mapTimestampColumn, profileColumnTypeLabel } from "./profileColumnModel";
+
+describe("Build Profile workspace layout", () => {
+ it("bounds the modal body and delegates scrolling to its panes", () => {
+ expect(profileBuilderModalClassName).toContain("h-[calc(100dvh-2rem)]");
+ // The body must shrink and stop owning scroll, and its panes must share the
+ // height. Asserted as utilities because a stylesheet shipped alongside the
+ // library silently does nothing in a consumer that never imports it.
+ expect(profileBuilderModalClassName).toContain(
+ "[&>[data-slot=modal-body]]:min-h-0",
+ );
+ expect(profileBuilderModalClassName).toContain(
+ "[&>[data-slot=modal-body]]:overflow-hidden",
+ );
+ expect(profileBuilderModalClassName).toContain(
+ "[&>[data-slot=modal-body]>*]:flex-1",
+ );
+ });
+});
+
+describe("Build Profile timestamp mapping", () => {
+ it("marks exactly one sampled column as the timestamp date-range column", () => {
+ expect(
+ mapTimestampColumn(
+ [
+ { name: "created_at", type: "string" },
+ { name: "updated_at", type: "datetime", kind: "timestamp" },
+ ],
+ "created_at",
+ ),
+ ).toEqual([
+ { name: "created_at", type: "datetime", kind: "timestamp" },
+ { name: "updated_at", type: "datetime" },
+ ]);
+ });
+});
+
+describe("Build Profile structured type labels", () => {
+ it("uses readable labels without changing serialized values", () => {
+ expect(profileColumnTypeLabel("key_value")).toBe("KeyValue{}");
+ expect(profileColumnTypeLabel("key_values")).toBe("[]KeyValue");
+ expect(profileColumnTypeLabel("json")).toBe("JSON");
+ expect(profileColumnTypeLabel("duration")).toBe("duration");
+ });
+});
diff --git a/packages/ui/src/profiles/profileBuilder.tsx b/packages/ui/src/profiles/profileBuilder.tsx
new file mode 100644
index 00000000..c28e4f41
--- /dev/null
+++ b/packages/ui/src/profiles/profileBuilder.tsx
@@ -0,0 +1,87 @@
+import { Button } from "../components/button";
+import { Icon } from "../data/Icon";
+import { UiDatabase } from "../icons";
+import {
+ createContext,
+ useContext,
+ useEffect,
+ useRef,
+ useState,
+ type ReactNode
+} from "react";
+import { savedConnectionID } from "./connectionBrowserModel";
+import {
+ ProfileBuilderWorkspace,
+ type ProfileDraft
+} from "./profileBuilderWorkspace";
+
+const ProfileBuilderAutoOpenContext = createContext(false);
+
+export function ProfileBuilderAutoOpen({ children }: { children: ReactNode }) {
+ return (
+
+ {children}
+
+ );
+}
+
+export function ProfileQueryBuilderField({
+ input,
+ rootValue,
+ onRootChange
+}: {
+ input: ReactNode;
+ rootValue: ProfileDraft;
+ onRootChange?: ((next: Record) => void) | undefined;
+}) {
+ const [open, setOpen] = useState(false);
+ const autoOpen = useContext(ProfileBuilderAutoOpenContext);
+ const autoOpened = useRef(false);
+ const connection = rootValue.provider?.connection ?? "";
+ const connectionID = savedConnectionID(connection);
+
+ useEffect(() => {
+ if (!autoOpen || autoOpened.current || !connectionID || !onRootChange) {
+ return;
+ }
+ autoOpened.current = true;
+ setOpen(true);
+ }, [autoOpen, connectionID, onRootChange]);
+
+ return (
+
+ {input}
+
+ setOpen(true)}
+ >
+
+ {!connectionID ? (
+
+ Choose a saved connection to browse its catalog and sample rows.
+ Inline URLs can still be configured manually.
+
+ ) : null}
+
+ {open && connectionID && onRootChange ? (
+
setOpen(false)}
+ />
+ ) : null}
+ & {
+ profile?: string;
+ query?: string;
+ provider?: ProfileProvider;
+ params?: ParamDraft[];
+ columns?: ProfileColumn[];
+ /** The row caps this profile sets for itself; unset ones take their default. */
+ limits?: ProfileRowLimits;
+};
+
+type SampleResult = QueryBrowserResult & {
+ columns: ProfileColumn[];
+ renderedQuery: string;
+};
+
+// Modal's body is a flex child. It must be allowed to shrink and must not own
+// scrolling, otherwise QueryBrowser's intrinsic minimum height expands the
+// whole workspace and pushes the editor/results below the dialog viewport.
+//
+// These are utilities rather than a stylesheet on purpose: a library CSS asset
+// only reaches a consumer that remembers to import it, whereas Tailwind scans
+// this source and folds the rules into the dist/styles.css every consumer
+// already loads.
+export const profileBuilderModalClassName =
+ "h-[calc(100dvh-2rem)] [&>[data-slot=modal-body]]:flex [&>[data-slot=modal-body]]:min-h-0 [&>[data-slot=modal-body]]:overflow-hidden [&>[data-slot=modal-body]>*]:flex-1 [&>[data-slot=modal-body]>*]:h-auto [&>[data-slot=modal-body]>*]:min-h-0";
+
+export function ProfileBuilderWorkspace({
+ connectionID,
+ rootValue,
+ onApply,
+ onClose,
+}: {
+ connectionID: string;
+ rootValue: ProfileDraft;
+ onApply: (next: Record) => void;
+ onClose: () => void;
+}) {
+ const baseUrl = browserBaseUrl(connectionID);
+ const descriptor = useQuery({
+ queryKey: ["profile-builder-descriptor", connectionID],
+ queryFn: () => fetchJSON(baseUrl),
+ retry: 0,
+ });
+ const initialProviderOptions = useMemo(
+ () => ({ ...rootValue.provider?.options }),
+ [rootValue.provider?.options],
+ );
+ const [query, setQuery] = useState(rootValue.query ?? "");
+ const [search, setSearch] = useState(
+ () => initialProviderOptions.search as EsSearch | undefined,
+ );
+ const [params, setParams] = useState(
+ () => rootValue.params ?? [],
+ );
+ const [liveOptions, setLiveOptions] = useState>(
+ initialProviderOptions,
+ );
+ const [catalogOptions, setCatalogOptions] = useState>(
+ {},
+ );
+ const [sampleParams, setSampleParams] = useState>(
+ () => defaultParamValues(params),
+ );
+ const [sampleColumns, setSampleColumns] = useState([]);
+ const [selectedColumns, setSelectedColumns] = useState>(
+ () => new Set(),
+ );
+ const [timestampColumn, setTimestampColumn] = useState(
+ () =>
+ rootValue.columns?.find((column) => column.kind === "timestamp")?.name ??
+ "",
+ );
+ const [selectedDatabase, setSelectedDatabase] = useState("");
+ const [limits, setLimits] = useState(
+ () => rootValue.limits,
+ );
+
+ useEffect(() => {
+ if (!query && descriptor.data?.defaultQuery) {
+ setQuery(descriptor.data.defaultQuery);
+ }
+ }, [descriptor.data?.defaultQuery, query]);
+
+ const explicitTargetKind =
+ liveOptions.targetKind ?? initialProviderOptions.targetKind;
+ const inspection = useInspection({
+ cacheKey: "profile-builder-inspection",
+ id: connectionID,
+ baseUrl,
+ enabled: descriptor.data?.catalog === true,
+ database: selectedDatabase,
+ fallbackDatabase: String(initialProviderOptions.database ?? ""),
+ target: String(liveOptions.index ?? initialProviderOptions.index ?? ""),
+ ...(typeof explicitTargetKind === "string"
+ ? { targetKind: explicitTargetKind }
+ : {}),
+ });
+ const browserOptions = useMemo(
+ () =>
+ mergeProviderOptions({
+ layers: [
+ descriptor.data?.initialOptions,
+ initialProviderOptions,
+ catalogOptions,
+ ],
+ database: inspection.sqlDatabase,
+ keepTargetKind: true,
+ }),
+ [
+ catalogOptions,
+ descriptor.data?.initialOptions,
+ initialProviderOptions,
+ inspection.sqlDatabase,
+ ],
+ );
+ // The specification is authored here, not merged from a layer, so it is
+ // stamped on last — including its absence, which a lower layer would
+ // otherwise reinstate after the author switched back to raw DSL.
+ const effectiveOptions = useCallback(
+ (options: Record) => {
+ const merged = mergeProviderOptions({
+ layers: [initialProviderOptions, catalogOptions, options],
+ database: inspection.sqlDatabase,
+ });
+ if (search) merged.search = search;
+ else delete merged.search;
+ return merged;
+ },
+ [catalogOptions, initialProviderOptions, inspection.sqlDatabase, search],
+ );
+
+ const paramSchema = useMemo(() => sampleParamSchema(params), [params]);
+ const existingColumns = rootValue.columns ?? [];
+ const existingNames = useMemo(
+ () => new Set(existingColumns.map((column) => column.name)),
+ [existingColumns],
+ );
+
+ const applyDraft = (mode: "query" | "merge" | "replace") => {
+ const chosen = mapTimestampColumn(
+ sampleColumns.filter((column) => selectedColumns.has(column.name)),
+ timestampColumn,
+ );
+ let columns = existingColumns;
+ if (mode === "merge") {
+ columns = mapTimestampColumn(
+ [
+ ...existingColumns,
+ ...chosen.filter((column) => !existingNames.has(column.name)),
+ ],
+ timestampColumn,
+ );
+ } else if (mode === "replace") {
+ if (
+ existingColumns.length > 0 &&
+ !window.confirm(
+ `Replace ${existingColumns.length} configured column${existingColumns.length === 1 ? "" : "s"}?`,
+ )
+ ) {
+ return;
+ }
+ columns = chosen;
+ }
+ const next: ProfileDraft = withProfileLimits(
+ {
+ ...rootValue,
+ query,
+ params,
+ provider: {
+ ...rootValue.provider,
+ options: effectiveOptions(liveOptions),
+ },
+ ...(mode === "query" ? {} : { columns }),
+ },
+ limits,
+ );
+ onApply(next);
+ onClose();
+ };
+
+ const footer = (
+
+
+ Cancel
+
+ applyDraft("query")}
+ >
+
+ applyDraft("merge")}
+ >
+
+ applyDraft("replace")}
+ >
+
+
+ );
+
+ return (
+
+
+ {Object.keys(paramSchema.properties ?? {}).length > 0 ? (
+
+
+ Temporary sample parameters (not saved)
+
+
+
+ ) : null}
+ {descriptor.isLoading ? (
+
Loading connection browser…
+ ) : descriptor.isError ? (
+
+ {errorMessage(
+ descriptor.error,
+ "Unable to load this connection browser",
+ )}
+
+ ) : descriptor.data ? (
+
{
+ setSearch(transition.search);
+ setQuery(transition.query);
+ }}
+ {...(limits ? { limits } : {})}
+ onLimitsChange={setLimits}
+ params={params}
+ onParamMappingChange={(edit) => {
+ setSearch(edit.search);
+ setParams(edit.params);
+ }}
+ paramValues={sampleParams}
+ paramRoles={paramRoles(params)}
+ compileBaseUrl={baseUrl}
+ className="h-full min-h-0"
+ onCatalogSelect={(node) => {
+ if (node.query) setQuery(node.query);
+ const nextOptions = node.options ?? {};
+ setCatalogOptions(nextOptions);
+ setLiveOptions({ ...browserOptions, ...nextOptions });
+ }}
+ execute={async (request) => {
+ const result = await fetchJSON(
+ "/api/v1/profile/sample",
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ profile: {
+ ...rootValue,
+ params,
+ profile: rootValue.profile || "sample",
+ query: request.query,
+ provider: {
+ ...rootValue.provider,
+ options: effectiveOptions(request.options),
+ },
+ },
+ params: sampleParams,
+ ...(request.pagination
+ ? { pagination: request.pagination }
+ : {}),
+ ...(request.debug ? { debug: true } : {}),
+ }),
+ },
+ );
+ setSampleColumns(result.columns ?? []);
+ setSelectedColumns(
+ new Set((result.columns ?? []).map((column) => column.name)),
+ );
+ return result;
+ }}
+ renderResults={({ defaultView }) => (
+
+
{defaultView}
+ {sampleColumns.length > 0 ? (
+
+ ) : null}
+
+ This saved connection does not expose a query browser.
+
+ )}
+
+ );
+}
+
+function WorkspaceMessage({
+ children,
+ error = false,
+}: {
+ children: ReactNode;
+ error?: boolean;
+}) {
+ return (
+
+ {children}
+
+ );
+}
+
+function sampleParamSchema(params: ParamDraft[]): JsonSchemaObject {
+ const properties: Record = {};
+ const required: string[] = [];
+ for (const param of params) {
+ const name = param.name?.trim();
+ if (!name) continue;
+ const property: JsonSchemaProperty = {
+ title: param.label || name,
+ ...(param.description ? { description: param.description } : {}),
+ ...(param.default !== undefined ? { default: param.default } : {}),
+ };
+ switch (param.type) {
+ case "number":
+ property.type = "number";
+ break;
+ case "boolean":
+ property.type = "boolean";
+ break;
+ case "date":
+ property.type = "string";
+ property.format = "date-time";
+ break;
+ default:
+ property.type = "string";
+ }
+ if (param.options?.length) property.enum = param.options;
+ properties[name] = property;
+ if (param.required) required.push(name);
+ }
+ return {
+ type: "object",
+ properties,
+ ...(required.length ? { required } : {}),
+ };
+}
+
+function errorMessage(error: unknown, fallback: string): string {
+ return error instanceof Error && error.message.trim()
+ ? error.message.trim()
+ : fallback;
+}
diff --git a/packages/ui/src/profiles/profileColumnFilter.test.ts b/packages/ui/src/profiles/profileColumnFilter.test.ts
new file mode 100644
index 00000000..cf4badbb
--- /dev/null
+++ b/packages/ui/src/profiles/profileColumnFilter.test.ts
@@ -0,0 +1,112 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { createElement } from "react";
+import { describe, expect, it } from "vitest";
+import { ProfileFieldEditorForm } from "./profileFieldEditor";
+import {
+ inferredFilterKind,
+ patchColumnFilter,
+ patchProfileField,
+ PROFILE_FILTER_DEFAULT_LIMIT,
+ type ProfileColumn,
+} from "./profileWizardModel";
+
+describe("patchColumnFilter", () => {
+ it("merges one knob without disturbing the others", () => {
+ expect(patchColumnFilter({ kind: "terms", limit: 10 }, { multi: false })).toEqual({
+ kind: "terms",
+ limit: 10,
+ multi: false,
+ });
+ });
+
+ // The distinction the server reads: an absent block means "infer this", an
+ // empty one would mean "override it with nothing".
+ it("drops the block once the last knob is cleared", () => {
+ expect(patchColumnFilter({ limit: 10 }, { limit: undefined })).toBeUndefined();
+ });
+
+ it("drops a block that was never anything", () => {
+ expect(patchColumnFilter(undefined, { field: undefined })).toBeUndefined();
+ });
+
+ it("creates the block on the first knob set", () => {
+ expect(patchColumnFilter(undefined, { limit: 25 })).toEqual({ limit: 25 });
+ });
+
+ // false and 0 are values an author chose; only undefined means "unset".
+ it("keeps a knob deliberately turned off", () => {
+ expect(patchColumnFilter(undefined, { lookup: false })).toEqual({ lookup: false });
+ });
+});
+
+describe("inferredFilterKind", () => {
+ it.each([
+ ["number", "range"],
+ ["duration", "range"],
+ ["bytes", "range"],
+ ["datetime", "time"],
+ ["boolean", "boolean"],
+ ["json", "none"],
+ ["key_values", "none"],
+ ["string", "terms"],
+ ["status", "terms"],
+ [undefined, "terms"],
+ ])("reads %s as %s, matching the server", (type, expected) => {
+ expect(inferredFilterKind({ name: "c", ...(type ? { type } : {}) })).toBe(expected);
+ });
+});
+
+describe("the filter block survives editing the rest of the column", () => {
+ it("is untouched by a label edit", () => {
+ const column: ProfileColumn = {
+ name: "tenant",
+ type: "string",
+ filter: { limit: 10, lookup: true },
+ };
+ expect(patchProfileField(column, { label: "Tenant" }).filter).toEqual({
+ limit: 10,
+ lookup: true,
+ });
+ });
+});
+
+describe("the column inspector", () => {
+ const render = (field: ProfileColumn) =>
+ renderToStaticMarkup(createElement(ProfileFieldEditorForm, { field, onChange: () => {} }));
+
+ it("offers the lookup limit for a value selection", () => {
+ const markup = render({ name: "tenant", type: "string" });
+
+ expect(markup).toContain("Values offered");
+ // Blank means the server's default, so the placeholder has to name it.
+ expect(markup).toContain(`placeholder="${PROFILE_FILTER_DEFAULT_LIMIT}"`);
+ expect(markup).toContain(`top ${PROFILE_FILTER_DEFAULT_LIMIT}`);
+ });
+
+ // A range is typed rather than picked, so a cap on a list it does not have
+ // would be a control with nothing behind it.
+ it("offers no lookup limit for a range", () => {
+ expect(render({ name: "latency_ms", type: "number" })).not.toContain("Values offered");
+ });
+
+ it("shows a declared limit in the collapsed summary", () => {
+ expect(render({ name: "tenant", type: "string", filter: { limit: 7 } })).toContain("top 7");
+ });
+
+ it("reports a filter turned off without claiming a control", () => {
+ const markup = render({ name: "tenant", type: "string", filter: { disabled: true } });
+ expect(markup).toContain(">off<");
+ });
+
+ // Enumerated values are the answer a lookup would fetch, so the two cannot
+ // both be on — and a disabled checkbox says so better than a silent override.
+ it("disables the lookup toggle once values are listed", () => {
+ const markup = render({
+ name: "tenant",
+ type: "string",
+ filter: { options: ["prod", "dev"] },
+ });
+ expect(markup).toContain("Values are listed above");
+ expect(markup).toContain("prod, dev");
+ });
+});
diff --git a/packages/ui/src/profiles/profileColumnModel.ts b/packages/ui/src/profiles/profileColumnModel.ts
new file mode 100644
index 00000000..1f265b24
--- /dev/null
+++ b/packages/ui/src/profiles/profileColumnModel.ts
@@ -0,0 +1,34 @@
+
+// One ProfileColumn, defined where the draft model is. The picker used to keep
+// a narrower copy of the same shape; two definitions of one concept drifted
+// apart unnoticed while they lived in separate modules and only collided once
+// the package exported both.
+import type { ProfileColumn } from "./profileWizardModel";
+
+export function profileColumnTypeLabel(type?: string) {
+ return type ? (PROFILE_COLUMN_TYPE_LABELS[type] ?? type) : "string";
+}
+
+/**
+ * mapTimestampColumn marks the chosen column as the profile's time range and
+ * clears the mark from whichever column previously held it.
+ */
+export function mapTimestampColumn(
+ columns: ProfileColumn[],
+ timestampColumn: string,
+): ProfileColumn[] {
+ return columns.map((column) => {
+ if (column.name === timestampColumn) {
+ return { ...column, type: "datetime", kind: "timestamp" };
+ }
+ if (column.kind !== "timestamp") return column;
+ const { kind: _kind, ...rest } = column;
+ return rest;
+ });
+}
+
+const PROFILE_COLUMN_TYPE_LABELS: Record = {
+ key_value: "KeyValue{}",
+ key_values: "[]KeyValue",
+ json: "JSON"
+};
diff --git a/packages/ui/src/profiles/profileColumnPicker.tsx b/packages/ui/src/profiles/profileColumnPicker.tsx
new file mode 100644
index 00000000..462f13c0
--- /dev/null
+++ b/packages/ui/src/profiles/profileColumnPicker.tsx
@@ -0,0 +1,82 @@
+import { Icon } from "../data/Icon";
+import { UiSqlColumn } from "../icons";
+
+// One ProfileColumn, defined where the draft model is. The picker used to keep
+// a narrower copy of the same shape; two definitions of one concept drifted
+// apart unnoticed while they lived in separate modules and only collided once
+// the package exported both.
+import type { ProfileColumn } from "./profileWizardModel";
+import { profileColumnTypeLabel } from "./profileColumnModel";
+export type { ProfileColumn };
+
+
+export function ColumnPicker({
+ columns,
+ selected,
+ existing,
+ onChange,
+ timestampColumn,
+ onTimestampColumnChange,
+}: {
+ columns: ProfileColumn[];
+ selected: Set;
+ existing: Set;
+ onChange: (next: Set) => void;
+ timestampColumn: string;
+ onTimestampColumnChange: (next: string) => void;
+}) {
+ return (
+
+
+
+
+
;
+ onClose: () => void;
+ onSuccess: (name: string) => void | Promise;
+}) {
+ const lookupFetcher = useOperationLookupFetcher(client);
+ const initialDraft = useMemo(() => cloneProfileDraft(initialValue), [initialValue]);
+ const initialSerialized = useMemo(() => JSON.stringify(initialDraft), [initialDraft]);
+ const [draft, setDraft] = useState(initialDraft);
+ const [section, setSection] = useState("general");
+ const [discovered, setDiscovered] = useState(initialDraft.columns ?? []);
+ const [sampledColumns, setSampledColumns] = useState([]);
+ const [sampleRows, setSampleRows] = useState[]>([]);
+ const [activeField, setActiveField] = useState(initialDraft.columns?.[0]?.name ?? "");
+ const [lastSampleSignature, setLastSampleSignature] = useState(() => profileSampleSignature(initialDraft));
+ const [rawValid, setRawValid] = useState(true);
+ const [saving, setSaving] = useState(false);
+ const [error, setError] = useState("");
+ const [replaceTarget, setReplaceTarget] = useState("");
+ const [confirmDiscard, setConfirmDiscard] = useState(false);
+ const [confirmResetColumns, setConfirmResetColumns] = useState(false);
+ const dirty = JSON.stringify(draft) !== initialSerialized;
+ const validationError = validateProfileEditorDraft(draft);
+ const sampleStale = profileSampleSignature(draft) !== lastSampleSignature;
+ const resetState = profileColumnResetState({
+ providerType: draft.provider?.type ?? "",
+ sampledColumnCount: sampledColumns.length,
+ sampleStale,
+ });
+
+ const fields = useProfileFieldState({
+ discovered,
+ configured: draft.columns ?? [],
+ activeName: activeField,
+ onConfiguredChange: (columns) => setDraft((current) => ({ ...current, columns })),
+ onActiveNameChange: setActiveField,
+ });
+
+ // A route can be refreshed or navigated away from; the dialog used to guard
+ // unsaved edits with confirmClose, so the route has to guard them too.
+ useEffect(() => {
+ if (!dirty) return;
+ const warn = (event: BeforeUnloadEvent) => event.preventDefault();
+ window.addEventListener("beforeunload", warn);
+ return () => window.removeEventListener("beforeunload", warn);
+ }, [dirty]);
+
+ const save = async (replaceExisting = false) => {
+ if (validationError) {
+ setError(validationError);
+ return;
+ }
+ if (!client.submitForm) {
+ setError("Profile updates are unavailable");
+ return;
+ }
+ setSaving(true);
+ setError("");
+ try {
+ const body = {
+ ...draft,
+ id: surfaceKey,
+ ...(replaceExisting ? { replaceExisting: true } : {}),
+ };
+ const response = await client.submitForm(
+ resolveProfileUpdatePath(action.path, surfaceKey),
+ action.method,
+ body,
+ );
+ if (!response.success) {
+ const message = response.error || response.message || "Profile update failed";
+ const target = profileUpdateConflictTarget(message);
+ if (target && !replaceExisting) {
+ setReplaceTarget(target);
+ return;
+ }
+ throw new Error(message);
+ }
+ await onSuccess(draft.profile!.trim());
+ } catch (saveError) {
+ setError(saveError instanceof Error ? saveError.message : "Profile update failed");
+ } finally {
+ setSaving(false);
+ }
+ };
+
+ const acceptSample = ({ columns, rows, sourceDraft }: ProfileSample) => {
+ setSampledColumns(structuredClone(columns));
+ setDiscovered(columns);
+ setSampleRows(rows);
+ setDraft((current) => ({
+ ...current,
+ columns: mergeSampledProfileColumns(current.columns ?? [], columns),
+ }));
+ setActiveField((current) => current || columns[0]?.name || "");
+ setLastSampleSignature(profileSampleSignature(sourceDraft));
+ };
+
+ const resetColumns = () => {
+ const first = sampledColumns[0];
+ if (!first) throw new Error("cannot reset columns without a sample");
+ setDraft((current) => resetProfileColumns(current, sampledColumns));
+ setActiveField(first.name);
+ setConfirmResetColumns(false);
+ };
+
+ const sectionContent = (
+
+ {section === "general" ?
: null}
+ {section === "source" ? (
+
+ ) : null}
+ {section === "parameters" ? (
+
+ ) : null}
+ {section === "advanced" ? (
+
+ ) : null}
+ {section === "raw" ? (
+
Loading YAML editor…}>
+
+ ) : null}
+
(() => {
+ const rail: WorkspacePaneSpec = {
+ id: "sections",
+ label: "Profile",
+ icon:
+ {fields.configuredCount} of {fields.available.length} included
+
+ {resetState.visible ? (
+ setConfirmResetColumns(true)}
+ >
+ Reset columns
+
+ ) : null}
+
+ Add column
+
+
+ ),
+ },
+ content: (
+ <>
+
+
+
{
+ if (fields.activeField) fields.setFieldSelection(fields.activeField, selected);
+ }}
+ canMoveUp={fields.canMoveUp}
+ canMoveDown={fields.canMoveDown}
+ onMoveUp={() => fields.moveActive(-1)}
+ onMoveDown={() => fields.moveActive(1)}
+ onRemove={fields.removeActive}
+ />
+
+ {profileFieldEditorEmptyMessage}
+
+ ),
+ },
+ {
+ id: "preview",
+ label: "Preview",
+ icon:
+ {sampleRows.length
+ ? `${sampleRows.length} sampled rows · updates as you edit`
+ : "No sample yet"}
+
+ ),
+ },
+ content:
+
+
+
+
+ Profiles
+
+ /
+
+ {initialDraft.profile ?? surfaceKey}
+
+ /
+ Edit
+
+ {error ? {error} : null}
+
+ {dirty ? "Unsaved changes" : "No changes"}
+
+
+ Discard
+
+ void save()}
+ >
+ {saving ? "Saving…" : "Save profile"}
+
+
+
+
+
+ {confirmDiscard ? (
+ setConfirmDiscard(false)}
+ title="Discard profile changes?"
+ size="sm"
+ footer={
+
+ setConfirmDiscard(false)}>
+ Keep editing
+
+
+ Discard changes
+
+
+ }
+ >
+
+ Your unsaved profile changes will be lost.
+
+
+ ) : null}
+
+ {confirmResetColumns ? (
+ setConfirmResetColumns(false)}
+ title="Reset columns from latest sample?"
+ size="sm"
+ footer={
+
+ setConfirmResetColumns(false)}>
+ Cancel
+
+
+ Reset columns
+
+
+ }
+ >
+
+ Replace {fields.configuredCount} configured column{fields.configuredCount === 1 ? "" : "s"} with {sampledColumns.length} column{sampledColumns.length === 1 ? "" : "s"} from the latest sample. Custom labels, expressions, formatting, filtering, ordering, and manually added columns will be removed. The profile will remain unsaved until you save it.
+
+
+ ) : null}
+
+ {replaceTarget ? (
+ setReplaceTarget("")}
+ title={`Replace ${replaceTarget}?`}
+ size="sm"
+ footer={
+
+ setReplaceTarget("")}>Cancel
+ {
+ setReplaceTarget("");
+ void save(true);
+ }}>
+ Replace profile
+
+
+ }
+ >
+
+ A profile named {replaceTarget} already exists. Its definition will be
+ overwritten, the current profile will be renamed, and dependent imports
+ will be updated atomically.
+
+
+ ) : null}
+
+ );
+}
+
+function sectionLabel(section: ProfileEditorSection): string {
+ return profileEditorSections.find((entry) => entry.id === section)!.label;
+}
+
diff --git a/packages/ui/src/profiles/profileEditorModel.test.ts b/packages/ui/src/profiles/profileEditorModel.test.ts
new file mode 100644
index 00000000..b0e2806d
--- /dev/null
+++ b/packages/ui/src/profiles/profileEditorModel.test.ts
@@ -0,0 +1,208 @@
+import type { JsonSchemaObject } from "../components/json-schema-form-types";
+import { beforeAll, describe, expect, it } from "vitest";
+import { configureProfiles } from "./profileApi";
+import { testProfileSchema } from "./testSchema";
+import {
+ mergeProfileProjection,
+ mergeSampledProfileColumns,
+ profileAdvancedKeys,
+ profileEditRoute,
+ profileEditSurfaceKey,
+ profileColumnResetState,
+ profileEditorSections,
+ profileRoute,
+ profileSampleSignature,
+ profileSchemaProjection,
+ profileUpdateConflictTarget,
+ resetProfileColumns,
+ validateProfileEditorDraft,
+} from "./profileEditorModel";
+
+describe("profile editor model", () => {
+ // The schema is the host's to supply; these tests supply a small one so the
+ // projection assertions below have an expected result that is obvious by inspection.
+ beforeAll(() => configureProfiles({ schema: testProfileSchema }));
+
+ it("defines a custom sectioned workspace independent of the schema layout", () => {
+ expect(profileEditorSections.map((section) => section.id)).toEqual([
+ "general",
+ "source",
+ "columns",
+ "parameters",
+ "advanced",
+ "raw",
+ ]);
+ });
+
+ it("merges projected schema fields without dropping opaque profile fields", () => {
+ const draft = {
+ profile: "OS",
+ params: [{ name: "host" }],
+ trace: { interval: "5s" },
+ context: { policy: { query: "select 1" } },
+ };
+
+ expect(
+ mergeProfileProjection(draft, ["params"], {
+ params: [{ name: "namespace" }],
+ }),
+ ).toEqual({
+ profile: "OS",
+ params: [{ name: "namespace" }],
+ trace: { interval: "5s" },
+ context: { policy: { query: "select 1" } },
+ });
+ expect(profileSchemaProjection(["params"]).properties).toHaveProperty("params");
+ });
+
+ // Which presets `use` offers is commons-db's schema to state, and its own
+ // tests assert that. What matters here is that a projection reaches nested
+ // properties intact rather than flattening or dropping them.
+ it("projects the advanced section down to the schema, nested properties included", () => {
+ expect(profileAdvancedKeys).toContain("processors");
+
+ const projection = profileSchemaProjection(profileAdvancedKeys);
+ const processors = projection.properties?.processors as JsonSchemaObject;
+ const use = (processors?.items as JsonSchemaObject)?.properties
+ ?.use as JsonSchemaObject;
+
+ expect(use?.enum).toEqual(["example.processor"]);
+ // An advanced key the schema does not declare contributes nothing, rather
+ // than an empty property the form would render as a blank control.
+ expect(projection.properties).not.toHaveProperty("aliases");
+ // profile and provider are required, but neither is in this projection.
+ expect(projection.required).toEqual([]);
+ });
+
+ it("merges samples by name while retaining configured and missing fields", () => {
+ expect(
+ mergeSampledProfileColumns(
+ [
+ { name: "message", type: "string", label: "Message" },
+ { name: "legacy", type: "string" },
+ ],
+ [
+ { name: "message", type: "json" },
+ { name: "duration", type: "duration" },
+ ],
+ ),
+ ).toEqual([
+ { name: "message", type: "string", label: "Message" },
+ { name: "legacy", type: "string" },
+ { name: "duration", type: "duration" },
+ ]);
+ });
+
+ it("resets configured columns to the latest sample order and metadata", () => {
+ const draft = {
+ profile: "OS",
+ provider: { type: "opensearch" },
+ columns: [
+ { name: "message", type: "string", label: "Message", cel: "message.trim()" },
+ { name: "manual", type: "boolean" },
+ ],
+ output: { unwrap: "hits" },
+ };
+ const sampled = [
+ { name: "duration", type: "number" },
+ { name: "message", type: "json" },
+ ];
+
+ const reset = resetProfileColumns(draft, sampled);
+
+ expect(reset).toEqual({
+ ...draft,
+ columns: sampled,
+ });
+ expect(reset.columns).not.toBe(sampled);
+ expect(reset.columns?.[0]).not.toBe(sampled[0]);
+ expect(() => resetProfileColumns(draft, [])).toThrow(
+ "Cannot reset profile columns without sampled columns",
+ );
+ });
+
+ it("offers reset only for OpenSearch with a current non-empty sample", () => {
+ expect(
+ profileColumnResetState({
+ providerType: "sql",
+ sampledColumnCount: 2,
+ sampleStale: false,
+ }),
+ ).toEqual({ visible: false, disabled: true, title: "" });
+ expect(
+ profileColumnResetState({
+ providerType: "opensearch",
+ sampledColumnCount: 0,
+ sampleStale: false,
+ }),
+ ).toEqual({
+ visible: true,
+ disabled: true,
+ title: "Run a sample before resetting columns",
+ });
+ expect(
+ profileColumnResetState({
+ providerType: "opensearch",
+ sampledColumnCount: 2,
+ sampleStale: true,
+ }),
+ ).toEqual({
+ visible: true,
+ disabled: true,
+ title: "Run another sample for the current source and query",
+ });
+ expect(
+ profileColumnResetState({
+ providerType: "opensearch",
+ sampledColumnCount: 2,
+ sampleStale: false,
+ }),
+ ).toEqual({
+ visible: true,
+ disabled: false,
+ title: "Replace configured columns with the latest sample",
+ });
+ });
+
+ it("tracks source changes and validates only editor-owned invariants", () => {
+ const draft = {
+ profile: "OS",
+ provider: { type: "sql", connection: "connection://db" },
+ query: "select 1",
+ columns: [{ name: "id" }],
+ };
+ expect(profileSampleSignature(draft)).not.toBe(
+ profileSampleSignature({ ...draft, query: "select 2" }),
+ );
+ expect(validateProfileEditorDraft(draft)).toBeNull();
+ expect(
+ validateProfileEditorDraft({
+ ...draft,
+ columns: [{ name: "id" }, { name: "id" }],
+ }),
+ ).toBe('Column name "id" is duplicated');
+ });
+
+ it("derives rename routes and structured conflict targets", () => {
+ expect(profileRoute("Service Logs.v2")).toBe("/profile-service-logs-v2");
+ expect(
+ profileUpdateConflictTarget(
+ 'PROFILE_NAME_CONFLICT: profile "OS" conflicts with existing profile "Linux"',
+ ),
+ ).toBe("Linux");
+ });
+
+ it("round-trips the editor route so a refresh reopens the same profile", () => {
+ const surfaceKey = "profile-service-logs-v2";
+ expect(profileEditRoute(surfaceKey)).toBe("/profile-service-logs-v2/edit");
+ expect(profileEditSurfaceKey(profileEditRoute(surfaceKey))).toBe(surfaceKey);
+ expect(profileEditSurfaceKey("/profile-service-logs-v2/edit/")).toBe(surfaceKey);
+ });
+
+ it("claims only profile edit routes, leaving detail and collection paths alone", () => {
+ expect(profileEditSurfaceKey("/profile-os2")).toBeNull();
+ expect(profileEditSurfaceKey("/profiles/edit")).toBeNull();
+ expect(profileEditSurfaceKey("/connection/edit")).toBeNull();
+ expect(profileEditSurfaceKey("/profile-os2/edit/columns")).toBeNull();
+ });
+});
diff --git a/packages/ui/src/profiles/profileEditorModel.ts b/packages/ui/src/profiles/profileEditorModel.ts
new file mode 100644
index 00000000..3f7abada
--- /dev/null
+++ b/packages/ui/src/profiles/profileEditorModel.ts
@@ -0,0 +1,224 @@
+import type { JsonSchemaObject } from "../components/json-schema-form-types";
+import { stripSurroundingDashes } from "../lib/string";
+import { profileSchema } from "./profileApi";
+import { validateProfileParams } from "./profileParamModel";
+import type { ProfileColumn, ProfileWizardDraft } from "./profileWizardModel";
+
+/**
+ * The schema the raw-YAML editor validates against. It is read through the
+ * configured accessor rather than bundled: the document is generated from
+ * commons-db's Go types and served by the host, so a copy here would drift.
+ */
+export function profileEditorSchema(): JsonSchemaObject {
+ return profileSchema();
+}
+
+export const profileEditorSections = [
+ { id: "general", label: "General", hint: "Name, namespace, render mode" },
+ { id: "source", label: "Source & Query", hint: "Provider, connection, sample" },
+ { id: "columns", label: "Columns", hint: "Fields, labels, expressions" },
+ { id: "parameters", label: "Parameters", hint: "Named query inputs" },
+ { id: "advanced", label: "Advanced", hint: "Imports, aliases, processors, output" },
+ { id: "raw", label: "Raw YAML", hint: "Edit the document directly" },
+] as const;
+
+export type ProfileEditorSection = (typeof profileEditorSections)[number]["id"];
+
+export const profileAdvancedKeys = ["imports", "aliases", "ignore", "processors", "output"];
+
+export type ProfileSectionStatus = {
+ badge?: string | undefined;
+ attention?: boolean | undefined;
+};
+
+/**
+ * Rail annotations per section. The route replaced tabs with a vertical rail,
+ * which has room to say how much each section holds — so a stale sample or an
+ * empty column set is visible without opening the section.
+ */
+export function profileEditorSectionStatus({
+ draft,
+ availableColumns,
+ sampleStale,
+}: {
+ draft: ProfileWizardDraft;
+ availableColumns: number;
+ sampleStale: boolean;
+}): Record {
+ const configured = draft.columns?.length ?? 0;
+ const params = Array.isArray(draft.params) ? draft.params.length : 0;
+ const advanced = profileAdvancedKeys.filter((key) =>
+ Object.prototype.hasOwnProperty.call(draft, key),
+ ).length;
+ return {
+ general: { attention: !draft.profile?.trim() },
+ source: {
+ badge: draft.provider?.type || undefined,
+ attention: sampleStale || !draft.provider?.type?.trim(),
+ },
+ columns: {
+ badge: `${configured}/${Math.max(availableColumns, configured)}`,
+ attention: configured === 0,
+ },
+ parameters: { badge: params ? String(params) : undefined },
+ advanced: { badge: advanced ? String(advanced) : undefined },
+ raw: {},
+ };
+}
+
+export function cloneProfileDraft(
+ value: Record,
+): ProfileWizardDraft {
+ return structuredClone(value) as ProfileWizardDraft;
+}
+
+export function profileSchemaProjection(keys: string[]): JsonSchemaObject {
+ const properties = Object.fromEntries(
+ keys.flatMap((key) => {
+ const property = profileSchema().properties?.[key];
+ return property ? [[key, property]] : [];
+ }),
+ );
+ return {
+ type: "object",
+ properties,
+ required: (profileSchema().required ?? []).filter((key) => keys.includes(key)),
+ };
+}
+
+export function providerOptionsSchema(providerType: string): JsonSchemaObject {
+ const definition = profileSchema().$defs?.[providerType];
+ const options = definition?.properties?.options;
+ if (!options || options.type !== "object") {
+ return { type: "object", properties: {}, additionalProperties: true };
+ }
+ return options as JsonSchemaObject;
+}
+
+export function providerTypes(): string[] {
+ const values = profileSchema().properties?.provider?.properties?.type?.enum;
+ return Array.isArray(values)
+ ? values.filter((value): value is string => typeof value === "string")
+ : [];
+}
+
+export function mergeProfileProjection(
+ draft: ProfileWizardDraft,
+ keys: string[],
+ next: Record,
+): ProfileWizardDraft {
+ const merged = { ...draft };
+ for (const key of keys) delete merged[key];
+ for (const key of keys) {
+ if (Object.prototype.hasOwnProperty.call(next, key)) merged[key] = next[key];
+ }
+ return merged;
+}
+
+export function mergeSampledProfileColumns(
+ configured: ProfileColumn[],
+ sampled: ProfileColumn[],
+): ProfileColumn[] {
+ const configuredNames = new Set(configured.map((column) => column.name));
+ return [
+ ...configured.map((column) => ({ ...column })),
+ ...sampled
+ .filter((column) => !configuredNames.has(column.name))
+ .map((column) => ({ ...column })),
+ ];
+}
+
+export function resetProfileColumns(
+ draft: ProfileWizardDraft,
+ sampled: ProfileColumn[],
+): ProfileWizardDraft {
+ if (sampled.length === 0) {
+ throw new Error("Cannot reset profile columns without sampled columns");
+ }
+ return { ...draft, columns: structuredClone(sampled) };
+}
+
+export function profileColumnResetState({
+ providerType,
+ sampledColumnCount,
+ sampleStale,
+}: {
+ providerType: string;
+ sampledColumnCount: number;
+ sampleStale: boolean;
+}) {
+ if (providerType !== "opensearch") {
+ return { visible: false, disabled: true, title: "" };
+ }
+ if (sampledColumnCount === 0) {
+ return {
+ visible: true,
+ disabled: true,
+ title: "Run a sample before resetting columns",
+ };
+ }
+ if (sampleStale) {
+ return {
+ visible: true,
+ disabled: true,
+ title: "Run another sample for the current source and query",
+ };
+ }
+ return {
+ visible: true,
+ disabled: false,
+ title: "Replace configured columns with the latest sample",
+ };
+}
+
+export function profileSampleSignature(draft: ProfileWizardDraft): string {
+ return JSON.stringify({
+ provider: draft.provider ?? {},
+ query: draft.query ?? "",
+ });
+}
+
+export function validateProfileEditorDraft(
+ draft: ProfileWizardDraft,
+): string | null {
+ if (!draft.profile?.trim()) return "Profile name is required";
+ if (!draft.provider?.type?.trim()) return "Provider type is required";
+ const names = new Set();
+ for (const column of draft.columns ?? []) {
+ const name = column.name.trim();
+ if (!name) return "Every column needs a name";
+ if (names.has(name)) return `Column name "${name}" is duplicated`;
+ names.add(name);
+ }
+ return validateProfileParams(draft.params, draft.provider?.type);
+}
+
+export function profileUpdateConflictTarget(error: string): string | null {
+ if (!error.includes("PROFILE_NAME_CONFLICT")) return null;
+ return error.match(/existing profile "([^"]+)"/)?.[1] ?? null;
+}
+
+export function profileRoute(name: string): string {
+ const slug = stripSurroundingDashes(
+ Array.from(name.trim().toLowerCase())
+ .map((character) =>
+ /[a-z0-9]/.test(character)
+ ? character
+ : /[ ._/-]/.test(character)
+ ? "-"
+ : "",
+ )
+ .join(""),
+ );
+ return `/profile-${slug}`;
+}
+
+/** Deep-linkable editor route for a profile surface (`profile-os2`). */
+export function profileEditRoute(surfaceKey: string): string {
+ return `/${surfaceKey}/edit`;
+}
+
+/** Surface key an edit route addresses, or null when the path is not one. */
+export function profileEditSurfaceKey(pathname: string): string | null {
+ return pathname.match(/^\/(profile-[^/]+)\/edit\/?$/)?.[1] ?? null;
+}
diff --git a/packages/ui/src/profiles/profileEditorPreview.tsx b/packages/ui/src/profiles/profileEditorPreview.tsx
new file mode 100644
index 00000000..543b810f
--- /dev/null
+++ b/packages/ui/src/profiles/profileEditorPreview.tsx
@@ -0,0 +1,71 @@
+import type { ProfileColumn } from "./profileWizardModel";
+
+/**
+ * The configured columns applied to the rows returned by the last sample, so
+ * the effect of including a field, relabelling it or hiding it is visible
+ * without leaving the editor. Rows only exist after a sample runs — there is no
+ * placeholder data, because a fabricated preview is worse than none.
+ */
+export function ProfileEditorPreview({
+ columns,
+ rows,
+}: {
+ columns: ProfileColumn[];
+ rows: Record[];
+}) {
+ const shown = columns.filter((column) => !column.hidden);
+
+ if (rows.length === 0 || shown.length === 0) {
+ return (
+
+ {shown.length === 0
+ ? "No columns included yet."
+ : "Run a sample in Source & Query to preview rows."}
+
+ );
+ }
+
+ return (
+
+
+
+
+ {shown.map((column) => (
+
+ {column.label ?? column.name}
+
+ ))}
+
+
+
+ {rows.map((row, index) => (
+
+ {shown.map((column) => (
+
+ {formatPreviewCell(
+ Object.prototype.hasOwnProperty.call(row, column.name)
+ ? row[column.name]
+ : column.source
+ ? row[column.source]
+ : undefined,
+ )}
+
+ ))}
+
+ ))}
+
+
+
;
+ onChange: (section: ProfileEditorSection) => void;
+}) {
+ return (
+
+ {profileEditorSections.map((section) => {
+ const active = section.id === value;
+ const { badge, attention } = status[section.id];
+ return (
+ onChange(section.id)}
+ >
+
+
+ {section.label}
+
+
+ {section.hint}
+
+
+ {attention ? (
+
+ {badge}
+
+ ) : null}
+
+ );
+ })}
+
+ );
+}
diff --git a/packages/ui/src/profiles/profileEditorRaw.test.tsx b/packages/ui/src/profiles/profileEditorRaw.test.tsx
new file mode 100644
index 00000000..2c7a1a4a
--- /dev/null
+++ b/packages/ui/src/profiles/profileEditorRaw.test.tsx
@@ -0,0 +1,64 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import { configureProfiles } from "./profileApi";
+import { testProfileSchema } from "./testSchema";
+import { ProfileEditorRaw } from "./profileEditorRaw";
+import { parseProfileYamlDocument, profileYamlFilename } from "./profileYaml";
+
+vi.mock("../monaco", () => ({
+ MonacoSchemaEditor: ({ height, value }: { height?: string | number; value: string }) => (
+
+ {value}
+
+ ),
+}));
+
+const draft = {
+ profile: "service-logs",
+ provider: { type: "opensearch" },
+ query: "GET service-logs/_search",
+};
+
+describe("raw profile YAML", () => {
+ // The Monaco editor validates against the host-supplied schema.
+ beforeAll(() => configureProfiles({ schema: testProfileSchema }));
+
+ it("fills the editor frame and exposes YAML import and export", () => {
+ const html = renderToStaticMarkup(
+ undefined}
+ onValidityChange={() => undefined}
+ />,
+ );
+
+ expect(html).toContain("Import YAML");
+ expect(html).toContain("Export YAML");
+ expect(html).toContain('accept=".yaml,.yml,application/yaml,text/yaml,text/x-yaml"');
+ expect(html).toContain('data-slot="profile-yaml-editor-frame"');
+ expect(html).toContain("[&>[data-slot=monaco-editor]]:h-full");
+ expect(html).toContain('data-height="100%"');
+ });
+
+ it("parses an imported YAML object", () => {
+ expect(
+ parseProfileYamlDocument(`
+profile: service-logs
+provider:
+ type: opensearch
+query: GET service-logs/_search
+`),
+ ).toEqual(draft);
+ });
+
+ it("rejects an imported YAML document that is not an object", () => {
+ expect(() => parseProfileYamlDocument("- service-logs\n")).toThrow(
+ "Profile YAML must contain an object",
+ );
+ });
+
+ it("uses a filesystem-safe YAML export name", () => {
+ expect(profileYamlFilename(" Service Logs / Prod ")).toBe("Service-Logs-Prod.yaml");
+ expect(profileYamlFilename(" ")).toBe("profile.yaml");
+ });
+});
diff --git a/packages/ui/src/profiles/profileEditorRaw.tsx b/packages/ui/src/profiles/profileEditorRaw.tsx
new file mode 100644
index 00000000..2c71e47c
--- /dev/null
+++ b/packages/ui/src/profiles/profileEditorRaw.tsx
@@ -0,0 +1,115 @@
+import { Button } from "../components/button";
+import { UiDownload, UiUpload } from "../icons";
+import { MonacoSchemaEditor } from "../monaco";
+import { useRef, useState, type ChangeEvent } from "react";
+import { stringify } from "yaml";
+import { profileEditorSchema } from "./profileEditorModel";
+import type { ProfileWizardDraft } from "./profileWizardModel";
+import { parseProfileYamlDocument, profileYamlFilename } from "./profileYaml";
+
+export function ProfileEditorRaw({
+ draft,
+ onChange,
+ onValidityChange
+}: {
+ draft: ProfileWizardDraft;
+ onChange: (draft: ProfileWizardDraft) => void;
+ onValidityChange: (valid: boolean) => void;
+}) {
+ const [value, setValue] = useState(() => stringify(draft));
+ const [parseError, setParseError] = useState("");
+ const fileInput = useRef(null);
+
+ const updateValue = (next: string) => {
+ setValue(next);
+ try {
+ const parsed = parseProfileYamlDocument(next);
+ setParseError("");
+ onValidityChange(true);
+ onChange(parsed);
+ } catch (error) {
+ setParseError(error instanceof Error ? error.message : "Invalid YAML");
+ onValidityChange(false);
+ }
+ };
+
+ const importYaml = async (event: ChangeEvent) => {
+ const input = event.currentTarget;
+ const file = input.files?.[0];
+ input.value = "";
+ if (!file) return;
+ try {
+ updateValue(await file.text());
+ } catch (error) {
+ setParseError(
+ `Unable to read ${file.name}: ${error instanceof Error ? error.message : String(error)}`,
+ );
+ onValidityChange(false);
+ }
+ };
+
+ return (
+
+
+
+ Raw YAML edits the complete profile. Invalid text is kept here while you
+ work; returning to another tab restores the last valid structured value.
+ YAML comments and key ordering are not preserved after structured edits.
+
+
+ fileInput.current?.click()}>
+
+ downloadProfileYaml(value, profileYamlFilename(draft.profile))}
+ >
+
+
+
+ {parseError ? (
+
{parseError}
+ ) : null}
+
+ {
+ if (!parseError) onValidityChange(state.status !== "invalid");
+ }}
+ onChange={updateValue}
+ />
+
+
+
+
+ );
+}
+
+export function ProfileSourceSection({
+ draft,
+ discovered,
+ sampleStale,
+ onChange,
+ onSample,
+}: EditorSectionProps & {
+ discovered: ProfileColumn[];
+ sampleStale: boolean;
+ onSample: (sample: ProfileSample) => void;
+}) {
+ const connectionID = profileConnectionID(draft.provider?.connection ?? "");
+ const providerType = draft.provider?.type ?? "";
+ return (
+
+
+
+
+
+ onChange({
+ ...draft,
+ provider: { ...draft.provider, type: event.target.value },
+ })
+ }
+ >
+ Choose a provider
+ {providerTypes().map((type) => {type} )}
+
+
+
+
+
+ {sampleStale ? (
+
+ Source or query settings changed after the latest sample. You can save,
+ but sampling again will verify the current field shape.
+
+ ) : null}
+
+ {connectionID ? (
+
+ ) : (
+
+
+