Skip to content

πŸͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(filters): share observed-metadata suggestions with the filter sidebar (LFE-11030) (#15886)

Nikita Kabardine71ee078de77
diff --git a/web/src/components/table/data-table-controls.tsx b/web/src/components/table/data-table-controls.tsx
index 9eb845658c..7d1d39ff5d 100644
--- a/web/src/components/table/data-table-controls.tsx
+++ b/web/src/components/table/data-table-controls.tsx
@@ -589,6 +589,8 @@ export function DataTableControls({
expanded={filter.expanded}
loading={filter.loading}
keyOptions={filter.keyOptions}
+ keyDetails={filter.keyDetails}
+ valueOptions={filter.valueOptions}
value={filter.value}
onChange={filter.onChange}
isActive={filter.isActive}
@@ -1097,6 +1099,8 @@ interface BooleanKeyValueFacetProps extends BaseFacetProps {
interface StringKeyValueFacetProps extends BaseFacetProps {
keyOptions?: string[];
+ keyDetails?: Record<string, string>;
+ valueOptions?: Record<string, string[]>;
value: StringKeyValueFilterEntry[];
onChange: (filters: StringKeyValueFilterEntry[]) => void;
keyPlaceholder?: string;
@@ -2194,6 +2198,8 @@ export function StringKeyValueFacet({
expanded: _expanded,
loading,
keyOptions,
+ keyDetails,
+ valueOptions,
value,
onChange,
isActive,
@@ -2222,6 +2228,8 @@ export function StringKeyValueFacet({
<KeyValueFilterBuilder
mode="string"
keyOptions={keyOptions}
+ keyDetails={keyDetails}
+ valueOptions={valueOptions}
activeFilters={value}
onChange={onChange}
keyPlaceholder={keyPlaceholder}
diff --git a/web/src/components/table/key-value-filter-builder.clienttest.tsx b/web/src/components/table/key-value-filter-builder.clienttest.tsx
index dc0b4afd81..41cbce3a54 100644
--- a/web/src/components/table/key-value-filter-builder.clienttest.tsx
+++ b/web/src/components/table/key-value-filter-builder.clienttest.tsx
@@ -31,6 +31,27 @@ describe("KeyValueFilterBuilder", () => {
expect(screen.getAllByText("missing-key")).not.toHaveLength(0);
});
+ it("keeps a facet with nothing enumerated on free text while typing a key", () => {
+ // A project with no scores offers no keys, so the pick-only combobox would
+ // trap the user: it must not appear just because the row now holds a
+ // half-typed key of its own.
+ render(
+ <KeyValueFilterBuilder
+ mode="numeric"
+ keyOptions={[]}
+ activeFilters={[]}
+ onChange={noop}
+ />,
+ );
+
+ fireEvent.click(screen.getByText("Add filter"));
+ const key = screen.getByPlaceholderText("Key");
+ fireEvent.change(key, { target: { value: "a" } });
+ fireEvent.change(key, { target: { value: "accuracy" } });
+
+ expect(screen.getByPlaceholderText("Key")).toHaveValue("accuracy");
+ });
+
it("preserves incomplete local filters across equivalent parent rerenders", () => {
const { rerender } = render(
<KeyValueFilterBuilder
diff --git a/web/src/components/table/key-value-filter-builder.tsx b/web/src/components/table/key-value-filter-builder.tsx
index c039ec46c4..13530f8e26 100644
--- a/web/src/components/table/key-value-filter-builder.tsx
+++ b/web/src/components/table/key-value-filter-builder.tsx
@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useId, useMemo, useState } from "react";
import { Button } from "@/src/components/ui/button";
import { Input } from "@/src/components/ui/input";
import {
@@ -10,6 +10,7 @@ import {
} from "@/src/components/ui/select";
import {
Popover,
+ PopoverAnchor,
PopoverContent,
PopoverTrigger,
} from "@/src/components/ui/popover";
@@ -22,6 +23,7 @@ import {
InputCommandList,
} from "@/src/components/ui/input-command";
import { MultiSelect } from "@/src/features/filters/components/multi-select";
+import { rankFacetOptions } from "@/src/features/filters/lib/facet-display";
import { Plus, X, Check, ChevronDown } from "lucide-react";
import { cn } from "@/src/utils/tailwind";
import { ScoreTag } from "@/src/components/score-tag";
@@ -63,6 +65,10 @@ type KeyValueFilterBuilderProps =
mode: "string";
keyOptions?: string[];
keyLevels?: KeyScoreLevels;
+ /** Offered key β†’ display-only type hint, shown beside the key option. */
+ keyDetails?: Record<string, string>;
+ /** Offered key β†’ its observed values, suggested under the value input. */
+ valueOptions?: Record<string, string[]>;
activeFilters: StringKeyValueFilterEntry[];
onChange: (filters: StringKeyValueFilterEntry[]) => void;
keyPlaceholder?: string;
@@ -88,6 +94,162 @@ const BOOLEAN_OPERATOR_LABELS = {
"<>": "does not equal",
} as const;
+// Enough to recognise what is available without turning the facet into a
+// scroll surface.
+const MAX_SUGGESTIONS = 10;
+
+/**
+ * Free-text input that offers observed values underneath β€” the sidebar half of
+ * the unified metadata suggestions (LFE-11030). Suggestions, not an
+ * enumeration: metadata keys and values are unbounded and the observed map only
+ * covers rows already loaded, so typing always wins and a picked row merely
+ * fills the input. Ranked with the search bar's own `filterRank` so both
+ * surfaces order identically.
+ */
+function SuggestingInput({
+ value,
+ onChange,
+ suggestions,
+ details,
+ placeholder,
+ disabled,
+}: {
+ value: string;
+ onChange: (value: string) => void;
+ suggestions: string[];
+ /** Suggestion β†’ display-only hint shown at the row's right edge. */
+ details?: Record<string, string>;
+ placeholder: string;
+ disabled?: boolean;
+}) {
+ const listId = useId();
+ const [focused, setFocused] = useState(false);
+ const [dismissed, setDismissed] = useState(false);
+ const [activeIndex, setActiveIndex] = useState(-1);
+
+ const ranked = useMemo(
+ // Drop an exact match: re-offering what is already typed covers the field
+ // with a row that changes nothing when picked.
+ () =>
+ rankFacetOptions(
+ suggestions.filter((s) => s !== value),
+ value,
+ ).slice(0, MAX_SUGGESTIONS),
+ [suggestions, value],
+ );
+ const open = focused && !dismissed && ranked.length > 0;
+ const active = open && activeIndex >= 0 ? ranked[activeIndex] : undefined;
+
+ const accept = (suggestion: string) => {
+ onChange(suggestion);
+ setDismissed(true);
+ setActiveIndex(-1);
+ };
+
+ const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
+ if (event.key === "Escape" && open) {
+ // Stop here: the sidebar may live in a Sheet that also closes on Escape.
+ event.stopPropagation();
+ setDismissed(true);
+ // Same reset as onBlur β€” a highlight kept across a dismissal would let a
+ // later ArrowDown-then-Enter accept it without the user re-picking.
+ setActiveIndex(-1);
+ return;
+ }
+ if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+ event.preventDefault();
+ if (!open) {
+ setDismissed(false);
+ return;
+ }
+ // Cycle through [-1 (nothing active), 0 … n-1] in both directions.
+ const step = event.key === "ArrowDown" ? 1 : -1;
+ const slots = ranked.length + 1;
+ setActiveIndex((current) => ((current + 1 + step + slots) % slots) - 1);
+ return;
+ }
+ if (event.key === "Enter" && active !== undefined) {
+ event.preventDefault();
+ accept(active);
+ }
+ };
+
+ return (
+ <Popover open={open}>
+ <PopoverAnchor asChild>
+ <Input
+ type="text"
+ placeholder={placeholder}
+ value={value}
+ onChange={(e) => {
+ onChange(e.target.value);
+ setDismissed(false);
+ setActiveIndex(-1);
+ }}
+ onFocus={() => setFocused(true)}
+ // Blur resets the whole interaction, not just focus: a stale
+ // `activeIndex` would let the next Enter accept a highlight the user
+ // never made, and a stale `dismissed` would survive into whichever row
+ // React reuses this index-keyed instance for after a row is deleted.
+ onBlur={() => {
+ setFocused(false);
+ setDismissed(false);
+ setActiveIndex(-1);
+ }}
+ onKeyDown={handleKeyDown}
+ disabled={disabled}
+ role="combobox"
+ aria-expanded={open}
+ aria-controls={listId}
+ aria-activedescendant={
+ active !== undefined ? `${listId}-${activeIndex}` : undefined
+ }
+ />
+ </PopoverAnchor>
+ <PopoverContent
+ // Suggestions read as an extension of the input, so they match its
+ // width instead of the popover default's 18rem floor.
+ className="w-(--radix-popover-trigger-width) min-w-0 p-1"
+ align="start"
+ // Focus stays in the input β€” this is a suggestion list, not a dialog.
+ onOpenAutoFocus={(e) => e.preventDefault()}
+ onCloseAutoFocus={(e) => e.preventDefault()}
+ >
+ <div id={listId} role="listbox">
+ {ranked.map((suggestion, i) => (
+ <button
+ key={suggestion}
+ id={`${listId}-${i}`}
+ type="button"
+ role="option"
+ aria-selected={i === activeIndex}
+ className={cn(
+ "flex w-full items-center gap-2 rounded-sm px-2 py-1 text-left text-sm",
+ i === activeIndex ? "bg-accent" : "hover:bg-accent",
+ )}
+ title={suggestion}
+ // mousedown, not click: the input must not blur before we apply.
+ onMouseDown={(e) => {
+ e.preventDefault();
+ accept(suggestion);
+ }}
+ >
+ <span className="min-w-0 flex-1 truncate" title={suggestion}>
+ {suggestion}
+ </span>
+ {details?.[suggestion] && (
+ <span className="text-muted-foreground shrink-0 text-xs">
+ {details[suggestion]}
+ </span>
+ )}
+ </button>
+ ))}
+ </div>
+ </PopoverContent>
+ </Popover>
+ );
+}
+
export function KeyValueFilterBuilder(props: KeyValueFilterBuilderProps) {
const {
mode,
@@ -98,6 +260,8 @@ export function KeyValueFilterBuilder(props: KeyValueFilterBuilderProps) {
keyPlaceholder = "Key",
} = props;
const availableValues = mode === "categorical" ? props.availableValues : {};
+ const keyDetails = mode === "string" ? props.keyDetails : undefined;
+ const valueOptions = mode === "string" ? props.valueOptions : undefined;
// Track which popover is open (by index)
const [openPopoverIndex, setOpenPopoverIndex] = useState<number | null>(null);
@@ -231,7 +395,6 @@ export function KeyValueFilterBuilder(props: KeyValueFilterBuilderProps) {
const availableValuesForKey = filter.key
? (availableValues[filter.key] ?? [])
: [];
- const hasKeyOptions = (keyOptions?.length ?? 0) > 0;
const mergedKeyOptions = Array.from(
new Set(
[
@@ -240,6 +403,16 @@ export function KeyValueFilterBuilder(props: KeyValueFilterBuilderProps) {
].filter((value) => value.length > 0),
),
);
+ // Free-text keys with suggestions where the key space is open-ended
+ // (metadata); a pick-only combobox where the backend enumerates it
+ // (score names) β€” offering an observed metadata key must never take
+ // away typing one the store has not seen (LFE-11030).
+ const suggestKeys = mode === "string";
+ // Gate on the OFFERED keys, never on mergedKeyOptions: that folds in the
+ // live-typed row keys, so a facet with nothing enumerated would flip
+ // from free text to pick-only after the first keystroke and trap the
+ // user at one character.
+ const hasKeyOptions = !suggestKeys && (keyOptions?.length ?? 0) > 0;
return (
<div
@@ -327,18 +500,17 @@ export function KeyValueFilterBuilder(props: KeyValueFilterBuilderProps) {
</PopoverContent>
</Popover>
) : (
- // Text input for free-form keys
- <Input
- placeholder={keyPlaceholder}
- value={filter.key}
- onChange={(e) => {
- // Only update the key, preserve the existing value
- handleFilterChange(index, {
- key: e.target.value,
- });
- }}
- className="flex-1"
- />
+ // Free-form key, with observed keys offered as suggestions.
+ // Only the key changes β€” the row's value is preserved.
+ <div className="min-w-0 flex-1">
+ <SuggestingInput
+ value={filter.key}
+ onChange={(key) => handleFilterChange(index, { key })}
+ suggestions={suggestKeys ? (keyOptions ?? []) : []}
+ details={keyDetails}
+ placeholder={keyPlaceholder}
+ />
+ </div>
)}
{/* Delete button */}
@@ -493,16 +665,14 @@ export function KeyValueFilterBuilder(props: KeyValueFilterBuilderProps) {
</SelectContent>
</Select>
- {/* String value input */}
- <Input
- type="text"
- placeholder="Value"
+ {/* String value input, with observed-value suggestions */}
+ <SuggestingInput
value={filter.value as string}
- onChange={(e) =>
- handleFilterChange(index, {
- value: e.target.value,
- })
+ onChange={(value) => handleFilterChange(index, { value })}
+ suggestions={
+ filter.key ? (valueOptions?.[filter.key] ?? []) : []
}
+ placeholder="Value"
disabled={!filter.key}
/>
</>
diff --git a/web/src/components/table/use-cases/observations.tsx b/web/src/components/table/use-cases/observations.tsx
index a5088ef2ea..de1b613f6e 100644
--- a/web/src/components/table/use-cases/observations.tsx
+++ b/web/src/components/table/use-cases/observations.tsx
@@ -17,6 +17,7 @@ import {
import { TokenUsageBadge } from "@/src/components/token-usage-badge";
import { useQueryFilterState } from "@/src/features/filters/hooks/useFilterState";
import { usePaginationState } from "@/src/hooks/usePaginationState";
+import { useFacetOptionsWithObservedMetadata } from "@/src/hooks/useObservedMetadata";
import {
type UseSidebarFilterStateOptions,
useSidebarFilterState,
@@ -529,9 +530,17 @@ export default function ObservationsTable({
modelId,
]);
+ // Opt into the shared observed-metadata suggestions for the Metadata facet
+ // (LFE-11030). This table's rows fetch metadata per cell, so it reads the
+ // per-project map without contributing to it.
+ const facetOptions = useFacetOptionsWithObservedMetadata(
+ projectId,
+ newFilterOptions,
+ );
+
const queryFilter = useSidebarFilterState(
observationsFilterConfig,
- newFilterOptions,
+ facetOptions,
queryFilterOptions,
);
diff --git a/web/src/features/events/components/EventsTable.tsx b/web/src/features/events/components/EventsTable.tsx
index 9756df7c25..a04c4ce334 100644
--- a/web/src/features/events/components/EventsTable.tsx
+++ b/web/src/features/events/components/EventsTable.tsx
@@ -148,6 +148,7 @@ import {
} from "@/src/features/chart-view/lib/chartFilterCompatibility";
import { getEventsTableStatePolicy } from "@/src/features/events/lib/eventsTableStatePolicy";
import {
+ useFacetOptionsWithObservedMetadata,
useObservedMetadataPaths,
useObservedMetadataRecorder,
} from "@/src/hooks/useObservedMetadata";
@@ -659,10 +660,17 @@ export default function ObservationsEventsTable({
approxTotalCountIsPartialScope ||
Boolean(searchQuery && searchQuery.trim().length > 0);
+ // The sidebar's Metadata facet suggests the same observed keys/values the
+ // search bar does β€” one store, one projection (LFE-11030).
+ const facetOptions = useFacetOptionsWithObservedMetadata(
+ projectId,
+ filterOptions,
+ );
+
const queryFilter = useSidebarFilterPresentation(
filterCore,
eventsFilterConfig,
- filterOptions,
+ facetOptions,
{
loading: isFilterOptionsPending,
loadingColumns,
@@ -720,11 +728,9 @@ export default function ObservationsEventsTable({
// Metadata key paths are not server-enumerated: merge the persisted
// per-project map of paths observed on previously loaded rows (recorded
// below, once the table data hook provides the rows) into the observed
- // options, so `metadata.` completes with real keys and their types.
- const observedMetadataPaths = useObservedMetadataPaths(
- projectId,
- searchBarMode,
- );
+ // options, so `metadata.` completes with real keys and their types. The
+ // sidebar's Metadata facet reads the same map (see facetOptions above).
+ const observedMetadataPaths = useObservedMetadataPaths(projectId);
const observedOptions = useMemo(
() =>
@@ -884,11 +890,14 @@ export default function ObservationsEventsTable({
// Record the visible rows' metadata paths into the persisted per-project
// suggestions map (read above into observedMetadataPaths). Same sampling as
- // the AI context below; runs once per fetch (rows identity).
+ // the AI context below; runs once per fetch (rows identity). Not gated on the
+ // search bar β€” the sidebar facet feeds from this map too β€” but embedded
+ // PREVIEW tables (`hideControls`: 10 rows under an arbitrary external filter)
+ // stay out: the per-key caps are drop-new-when-full, so a narrow preview's
+ // keys would crowd out the ones the project actually browses.
useObservedMetadataRecorder({
projectId,
- rows: observations.rows,
- enabled: searchBarMode,
+ rows: hideControls ? undefined : observations.rows,
});
// Project data context for the AI filter prompt: observed values (from
diff --git a/web/src/features/filters/hooks/useSidebarFilterState.tsx b/web/src/features/filters/hooks/useSidebarFilterState.tsx
index 70a58f79e5..63cd49c0eb 100644
--- a/web/src/features/filters/hooks/useSidebarFilterState.tsx
+++ b/web/src/features/filters/hooks/useSidebarFilterState.tsx
@@ -280,6 +280,10 @@ export interface StringKeyValueUIFilter extends BaseUIFilter {
type: "stringKeyValue";
value: StringKeyValueFilterEntry[]; // Array of active filter rows
keyOptions?: string[];
+ /** Offered key β†’ display-only type hint ("number", "object", …). */
+ keyDetails?: Record<string, string>;
+ /** Offered key β†’ its observed values, for the value input's suggestions. */
+ valueOptions?: Record<string, string[]>;
onChange: (filters: StringKeyValueFilterEntry[]) => void;
}
@@ -294,6 +298,24 @@ export type UIFilter =
const EMPTY_MAP: Map<string, number> = new Map();
+/**
+ * One offered facet option. `type` is the display-only hint client-side
+ * suggestion sources carry (observed metadata keys: "number", "object", …);
+ * server-enumerated options never set it.
+ */
+export type FacetOptionValue = SingleValueOption & { type?: string };
+
+/**
+ * The facet option payload a view hands the sidebar: `filterOptions` per
+ * column, plus whatever client-side suggestion source it opted into. Keyed
+ * lookups (`<column>.<key>`) carry a key's own values β€” that is how the
+ * metadata facet gets value suggestions (LFE-11030).
+ */
+export type FacetOptions = Record<
+ string,
+ (string | FacetOptionValue)[] | Record<string, string[]> | undefined
+>;
+
const mergeUniqueStrings = (...lists: (string[] | undefined)[]): string[] =>
Array.from(
new Set(
@@ -313,10 +335,7 @@ const SCORE_LEVEL_TAGGED_COLUMNS: Readonly<Record<string, string>> = {
const resolveKeyScoreLevels = (
column: string,
- options: Record<
- string,
- (string | SingleValueOption)[] | Record<string, string[]> | undefined
- >,
+ options: FacetOptions,
): KeyScoreLevels | undefined => {
const levelsKey = SCORE_LEVEL_TAGGED_COLUMNS[column];
const scoreNameLevels = levelsKey ? options[levelsKey] : undefined;
@@ -337,7 +356,7 @@ const resolveKeyScoreLevels = (
const resolveKnownKeyOptions = (
facetKeyOptions: string[] | undefined,
availableKeys:
- | (string | SingleValueOption)[]
+ | (string | FacetOptionValue)[]
| Record<string, string[]>
| undefined,
activeKeys: string[],
@@ -358,6 +377,43 @@ const resolveKnownKeyOptions = (
);
};
+/** The display-only type hints an offered key list carries, if any. */
+const resolveKeyDetails = (
+ availableKeys:
+ | (string | FacetOptionValue)[]
+ | Record<string, string[]>
+ | undefined,
+): Record<string, string> | undefined => {
+ if (!Array.isArray(availableKeys)) return undefined;
+ const out: Record<string, string> = {};
+ for (const option of availableKeys) {
+ if (typeof option !== "string" && option.type !== undefined) {
+ out[option.value] = option.type;
+ }
+ }
+ return Object.keys(out).length > 0 ? out : undefined;
+};
+
+/**
+ * Per-key value suggestions for a keyed facet, read from the `<column>.<key>`
+ * entries of the option map (the shape the observed-metadata projection and the
+ * search bar's completion planner both use).
+ */
+const resolveKeyedValueOptions = (
+ column: string,
+ keyOptions: string[] | undefined,
+ options: FacetOptions,
+): Record<string, string[]> | undefined => {
+ if (keyOptions === undefined) return undefined;
+ const out: Record<string, string[]> = {};
+ for (const key of keyOptions) {
+ const values = options[`${column}.${key}`];
+ if (!Array.isArray(values) || values.length === 0) continue;
+ out[key] = values.map((v) => (typeof v === "string" ? v : v.value));
+ }
+ return Object.keys(out).length > 0 ? out : undefined;
+};
+
const mergeAvailableValuesWithActiveFilters = (
availableValues: Record<string, string[]>,
activeFilters: KeyValueFilterEntry[],
@@ -938,10 +994,7 @@ export type SidebarFilterPresentationOptions = Pick<
export function useSidebarFilterPresentation(
core: SidebarFilterStateCore,
config: FilterConfig,
- options: Record<
- string,
- (string | SingleValueOption)[] | Record<string, string[]> | undefined
- >,
+ options: FacetOptions,
presentationOptions: SidebarFilterPresentationOptions = {},
) {
const { loading, loadingColumns } = presentationOptions;
@@ -1592,6 +1645,12 @@ export function useSidebarFilterPresentation(
value: activeFilters,
keyOptions,
+ keyDetails: resolveKeyDetails(availableKeys),
+ valueOptions: resolveKeyedValueOptions(
+ facet.column,
+ keyOptions,
+ options,
+ ),
loading: shouldShowLoading(facet.column),
expanded: expandedSet.has(facet.column),
isActive,
@@ -1931,10 +1990,7 @@ export function useSidebarFilterPresentation(
*/
export function useSidebarFilterState(
config: FilterConfig,
- options: Record<
- string,
- (string | SingleValueOption)[] | Record<string, string[]> | undefined
- >,
+ options: FacetOptions,
hookOptions: UseSidebarFilterStateOptions = DEFAULT_HOOK_OPTIONS,
) {
const core = useSidebarFilterStateCore(config, hookOptions);
diff --git a/web/src/features/filters/metadataSuggestionParity.clienttest.tsx b/web/src/features/filters/metadataSuggestionParity.clienttest.tsx
new file mode 100644
index 0000000000..573e997646
--- /dev/null
+++ b/web/src/features/filters/metadataSuggestionParity.clienttest.tsx
@@ -0,0 +1,168 @@
+/**
+ * The sidebar half of the unified metadata suggestions (LFE-11030): the
+ * Metadata facet reads the same observed-key/value map the search bar does,
+ * offered from the option map's `metadata` and `metadata.<key>` entries.
+ *
+ * The invariant worth pinning is that these stay SUGGESTIONS: the observed map
+ * only covers rows already loaded, so a key or value it has never seen must
+ * still be typeable.
+ */
+
+import { fireEvent, render, screen } from "@testing-library/react";
+import { KeyValueFilterBuilder } from "@/src/components/table/key-value-filter-builder";
+import { observedMetadataOptions } from "@/src/fns/observedMetadata/metadataPaths";
+import {
+ useSidebarFilterState,
+ type StringKeyValueUIFilter,
+} from "./hooks/useSidebarFilterState";
+import type { FilterConfig } from "./lib/filter-config";
+
+// The hook calls useQueryParam unconditionally even for the "memory" state
+// location used here; stub it out so no QueryParamProvider is needed.
+vi.mock("use-query-params", async () => {
+ const actual = await vi.importActual("use-query-params");
+ return {
+ ...actual,
+ StringParam: {},
+ useQueryParam: () => [null, () => {}] as const,
+ };
+});
+
+const METADATA_FILTER_CONFIG: FilterConfig = {
+ tableName: "observations",
+ columnDefinitions: [
+ {
+ id: "metadata",
+ name: "Metadata",
+ type: "stringObject",
+ internal: 'o."metadata"',
+ },
+ ],
+ facets: [{ type: "stringKeyValue", column: "metadata", label: "Metadata" }],
+};
+
+function MetadataFacetHarness() {
+ const queryFilter = useSidebarFilterState(
+ METADATA_FILTER_CONFIG,
+ observedMetadataOptions({
+ region: { type: "string", values: ["eu", "us"] },
+ retries: { type: "number" },
+ scope: { type: "object" },
+ }),
+ { stateLocation: "memory" },
+ );
+
+ const facet = queryFilter.filters.find(
+ (f): f is StringKeyValueUIFilter => f.column === "metadata",
+ );
+ if (!facet) throw new Error("metadata facet missing");
+
+ return (
+ <KeyValueFilterBuilder
+ mode="string"
+ keyOptions={facet.keyOptions}
+ keyDetails={facet.keyDetails}
+ valueOptions={facet.valueOptions}
+ activeFilters={facet.value}
+ onChange={facet.onChange}
+ />
+ );
+}
+
+describe("metadata suggestions in the filter sidebar", () => {
+ beforeAll(() => {
+ Element.prototype.scrollIntoView = vi.fn();
+ });
+
+ it("offers observed keys with their type hint, then the key's values", () => {
+ render(<MetadataFacetHarness />);
+ fireEvent.click(screen.getByText("Add filter"));
+
+ const key = screen.getByPlaceholderText("Key");
+ fireEvent.focus(key);
+ // Sorted by the projection, each with its observed JSON type as the hint.
+ expect(screen.getByText("region")).toBeInTheDocument();
+ expect(screen.getByText("number")).toBeInTheDocument();
+ fireEvent.mouseDown(screen.getByText("region"));
+ expect(key).toHaveValue("region");
+
+ const value = screen.getByPlaceholderText("Value");
+ fireEvent.focus(value);
+ fireEvent.mouseDown(screen.getByText("eu"));
+ expect(value).toHaveValue("eu");
+ });
+
+ it("ranks matches prefix-first, the way the search bar does", () => {
+ render(
+ <KeyValueFilterBuilder
+ mode="string"
+ keyOptions={["user.region", "region", "regional"]}
+ activeFilters={[]}
+ onChange={() => {}}
+ />,
+ );
+ fireEvent.click(screen.getByText("Add filter"));
+ const key = screen.getByPlaceholderText("Key");
+ fireEvent.focus(key);
+ fireEvent.change(key, { target: { value: "reg" } });
+
+ expect(
+ screen
+ .getAllByRole("option")
+ .map((option) => option.textContent?.trim() ?? ""),
+ ).toEqual(["region", "regional", "user.region"]);
+ });
+
+ it("never offers what is already typed, and picks with the keyboard", () => {
+ render(<MetadataFacetHarness />);
+ fireEvent.click(screen.getByText("Add filter"));
+
+ const key = screen.getByPlaceholderText("Key");
+ fireEvent.focus(key);
+ // A fully typed key is not re-offered β€” the list would cover the field with
+ // a row that changes nothing.
+ fireEvent.change(key, { target: { value: "scope" } });
+ expect(screen.queryAllByRole("option")).toHaveLength(0);
+
+ fireEvent.change(key, { target: { value: "sc" } });
+ fireEvent.keyDown(key, { key: "ArrowDown" });
+ fireEvent.keyDown(key, { key: "Enter" });
+ expect(key).toHaveValue("scope");
+
+ // Dismissing clears the highlight, by blur or by Escape: reopening the list
+ // must not let Enter accept a suggestion highlighted before the dismissal.
+ // The two dismissals reopen differently β€” blur reopens on focus, Escape
+ // keeps the list closed until an arrow key.
+ const dismissals = [
+ { typed: "re", dismiss: () => fireEvent.blur(key), reopen: () => {} },
+ {
+ typed: "reg",
+ dismiss: () => fireEvent.keyDown(key, { key: "Escape" }),
+ reopen: () => fireEvent.keyDown(key, { key: "ArrowDown" }),
+ },
+ ];
+ for (const { typed, dismiss, reopen } of dismissals) {
+ fireEvent.focus(key);
+ fireEvent.change(key, { target: { value: typed } });
+ fireEvent.keyDown(key, { key: "ArrowDown" });
+ dismiss();
+ fireEvent.focus(key);
+ reopen();
+ fireEvent.keyDown(key, { key: "Enter" });
+ expect(key).toHaveValue(typed);
+ }
+ });
+
+ it("still accepts a key and value the observed map has never seen", () => {
+ render(<MetadataFacetHarness />);
+ fireEvent.click(screen.getByText("Add filter"));
+
+ const key = screen.getByPlaceholderText("Key");
+ fireEvent.change(key, { target: { value: "never-observed" } });
+ const value = screen.getByPlaceholderText("Value");
+ fireEvent.change(value, { target: { value: "also-new" } });
+
+ expect(key).toHaveValue("never-observed");
+ expect(value).toHaveValue("also-new");
+ });
+});
diff --git a/web/src/hooks/useObservedMetadata.ts b/web/src/hooks/useObservedMetadata.ts
index 9963c55b4f..1da6ebd3c4 100644
--- a/web/src/hooks/useObservedMetadata.ts
+++ b/web/src/hooks/useObservedMetadata.ts
@@ -1,30 +1,46 @@
// Bridge between a table and the observed-metadata store: the recorder samples
// the currently visible rows' metadata into the persisted per-project key map
// (once per fetch β€” the rows identity only changes when new data lands), and
-// the reader selects that project's map for merging into a surface's option
-// map (fns/observedMetadata/metadataPaths.ts observedMetadataOptions). Split in
-// two because EventsTable derives its observed options before the table data
-// hook runs, while the recorder needs the loaded rows.
+// the readers project that map into the option-map entries both suggestion
+// surfaces look up (fns/observedMetadata/metadataPaths.ts). Split in two
+// because EventsTable derives its observed options before the table data hook
+// runs, while the recorder needs the loaded rows.
-import { useEffect } from "react";
+import { useEffect, useMemo } from "react";
import {
collectMetadataPathTypes,
METADATA_SAMPLE_ROWS,
+ observedMetadataOptions,
+ type MetadataSuggestion,
type StoredKeyInfo,
} from "@/src/fns/observedMetadata/metadataPaths";
import { useObservedMetadataStore } from "@/src/stores/observedMetadataStore";
/**
* The project's persisted metadata key→info map (type + sample values), or
- * undefined when disabled or nothing has been observed yet. Stable identity
- * between store writes.
+ * undefined when nothing has been observed yet. Stable identity between store
+ * writes.
*/
export function useObservedMetadataPaths(
projectId: string,
- enabled: boolean,
): Record<string, StoredKeyInfo> | undefined {
- return useObservedMetadataStore((s) =>
- enabled ? s.byProject[projectId]?.paths : undefined,
+ return useObservedMetadataStore((s) => s.byProject[projectId]?.paths);
+}
+
+/**
+ * A table's facet options with the project's observed-metadata suggestions
+ * merged in: keys under `metadata`, each key's sample values under
+ * `metadata.<key>`. The one-line opt-in for a sidebar whose `metadata` facet
+ * filters OBSERVATION metadata β€” a surface whose column is a different entity
+ * (session metadata) must not adopt it, its key space differs.
+ */
+export function useFacetOptionsWithObservedMetadata<
+ T extends Record<string, unknown>,
+>(projectId: string, options: T): T & Record<string, MetadataSuggestion[]> {
+ const paths = useObservedMetadataPaths(projectId);
+ return useMemo(
+ () => ({ ...options, ...observedMetadataOptions(paths) }),
+ [options, paths],
);
}
@@ -33,23 +49,22 @@ export function useObservedMetadataPaths(
* `MetadataDomainClient`) and union the observed top-level keys into the
* project's persisted map. Samples the same first rows as the AI-context
* path; the store skips the write when nothing changed, so re-running on
- * each fetch settles immediately.
+ * each fetch settles immediately. Absent rows are a no-op, which is how a
+ * table opts out.
*/
export function useObservedMetadataRecorder({
projectId,
rows,
- enabled,
}: {
projectId: string;
rows: ReadonlyArray<{ metadata?: unknown }> | undefined;
- enabled: boolean;
}): void {
const recordPaths = useObservedMetadataStore((s) => s.actions.recordPaths);
useEffect(() => {
- if (!enabled || rows === undefined || rows.length === 0) return;
+ if (rows === undefined || rows.length === 0) return;
const collected = collectMetadataPathTypes(
rows.slice(0, METADATA_SAMPLE_ROWS).map((r) => r.metadata),
);
if (collected.size > 0) recordPaths(projectId, collected);
- }, [enabled, rows, projectId, recordPaths]);
+ }, [rows, projectId, recordPaths]);
}