@rebasepro/admin 0.13.1-canary.gef9608c → 0.14.0

package/src/components/CollectionViewBinding/CollectionViewActions.tsx

@@ -74,7 +74,7 @@ export function CollectionViewActions<M extends Record<string, unknown>>({
                 size="small"
                 variant="filled"
                 color="primary">
-                Add {collection.singularName ?? collection.name}
+                {t("add_specific", { name: collection.singularName ?? collection.name })}
             </Button>
             : <Button
                 id={`add_entity_${path}`}

package/src/components/CollectionViewBinding/CollectionViewBinding.tsx

@@ -28,6 +28,7 @@ import { ReferencePreview } from "../../preview";
 import {
     CollectionScopeProvider,
     OnColumnResizeParams,
+    getRedundantChildViewColumnIds,
     useAnalyticsController,
     useAuthController,
     useColumnIds,
@@ -281,8 +282,15 @@ const CollectionViewBindingInner = React.memo(
         useEffect(() => {
             if (!urlView && viewMode !== defaultViewMode) {
                 // View came from saved config but URL doesn't have it - update URL without push
-                setSearchParams((prev) => {
-                    const next = new URLSearchParams(prev);
+                // Built from `window.location.search`, not React Router's
+                // `prev`. The table controller writes the filter, sort and
+                // search params with `history.replaceState`, which React Router
+                // never observes — so `prev` is a stale snapshot, and merging
+                // into it silently dropped whatever it had not seen. Switching
+                // view mode after typing a search wiped `search=` from the URL,
+                // and the next reload came back unfiltered.
+                setSearchParams(() => {
+                    const next = new URLSearchParams(window.location.search);
                     next.set(VIEW_MODE_PARAM, viewMode);
                     return next;
                 }, { replace: true });
@@ -294,8 +302,10 @@ const CollectionViewBindingInner = React.memo(
             setViewModeState(newMode);
 
             // Update URL with __view param via React Router
-            setSearchParams((prev) => {
-                const next = new URLSearchParams(prev);
+            setSearchParams(() => {
+                // See the note above: the live URL is the only writer both
+                // this and the table controller agree on.
+                const next = new URLSearchParams(window.location.search);
                 if (newMode === defaultViewMode) {
                     next.delete(VIEW_MODE_PARAM);
                 } else {
@@ -687,7 +697,16 @@ parentEntityIds: parentEntityIds ?? EMPTY_ARRAY,
             // Each child view gets a column that jumps to its tab. Keyed by the
             // view's collection slug, which is the relation key — two relations
             // to the same target used to collapse onto one column id here.
-            const subcollectionsList = getEntityChildViews(collection).map(v => v.collection as AdminCollection);
+            //
+            // Except where the relation was declared as a property and so already
+            // has a column showing the child rows: the button then repeated that
+            // column's heading verbatim. Filtered here as well as in
+            // `useColumnIds` so no id is displayed without a delegate to build it,
+            // and so the column picker does not offer the one back.
+            const redundant = getRedundantChildViewColumnIds(collectionWithLocalOrder);
+            const subcollectionsList = getEntityChildViews(collection)
+                .map(v => v.collection as AdminCollection)
+                .filter(child => !redundant.has(getSubcollectionColumnId(child)));
             const subcollectionColumns: AdditionalFieldDelegate<M, any>[] = subcollectionsList.map((subcollection: AdminCollection) => {
                 return {
                     key: getSubcollectionColumnId(subcollection),
@@ -720,7 +739,7 @@ parentEntityIds: parentEntityIds ?? EMPTY_ARRAY,
                 ...(collection.additionalFields ?? EMPTY_ARRAY),
                 ...subcollectionColumns
             ];
-        }, [collection, path, sidePanelController]);
+        }, [collection, collectionWithLocalOrder, path, sidePanelController]);
 
         const updateLastDeleteTimestamp = useCallback(() => {
             setLastDeleteTimestamp(Date.now());
@@ -1458,6 +1477,7 @@ function EntityIdHeaderWidget({
                         <div className="flex p-2 w-full gap-2">
                             <TextField
                                 autoFocus={openPopup}
+                                aria-label={t("find_entity_by_id")}
                                 placeholder={t("find_entity_by_id")}
                                 size="small"
                                 onChange={(e) => {

package/src/components/CollectionViewBinding/CollectionViewStartActions.tsx

@@ -104,6 +104,13 @@ parentEntityIds,
         </Tooltip>
     );
 
+    // Whether the toolbar is showing icon-only controls. The filters button
+    // drops its label — and its icon a size with it — on a narrow layout as
+    // well as in the split view, and the sort and clear controls beside it
+    // follow: keyed on `compact` alone they stayed 20px next to a 16px filter
+    // icon at every width below `largeLayout`.
+    const iconOnlyToolbar = !largeLayout || Boolean(compact);
+
     const filtersButton = resolvedProperties && tableController.setFilterValues && (
         <Tooltip title={t("filters")}
             key={"filters_tooltip"}>
@@ -147,6 +154,7 @@ parentEntityIds,
             key={"sort_button"}
             tableController={tableController}
             properties={resolvedProperties}
+            compact={iconOnlyToolbar}
         />
     );
 
@@ -170,6 +178,7 @@ parentEntityIds,
         <ClearFilterSortButton
             key={"clear_filter"}
             tableController={tableController}
+            compact={iconOnlyToolbar}
             enabled={!collection.fixedFilter}/>,
         filterPresetsButton
     ];

package/src/components/CollectionViewBinding/EntityCardBinding.tsx

@@ -17,9 +17,13 @@ import {
 import { useAnalyticsController } from "@rebasepro/app";
 import { IconForView } from "@rebasepro/app";
 import { useCollectionSlotKeys, useEntitySlots } from "./usePreviewSlots";
-import { SlotValue } from "./SlotValue";
+import { Highlighted } from "./SearchHighlight";
+import { useSearchExplanation, MatchExplanation, fieldLabel } from "./SearchExplanation";
+import { SlotValue, TagChips } from "./SlotValue";
 
 export type EntityCardBindingProps<M extends Record<string, unknown> = Record<string, unknown>> = {
+    /** The active search, so a card can mark the hit and say where it was. */
+    searchString?: string;
     entity: Entity<M>;
     collection: AdminCollection<M>;
     onClick?: (entity: Entity<M>) => void;
@@ -45,7 +49,8 @@ export function EntityCardBinding<M extends Record<string, unknown> = Record<str
     highlighted,
     onSelectionChange,
     selectionEnabled,
-    size = "m"
+    size = "m",
+    searchString
 }: EntityCardBindingProps<M>) {
     const authController = useAuthController();
     const analyticsController = useAnalyticsController();
@@ -63,6 +68,15 @@ export function EntityCardBinding<M extends Record<string, unknown> = Record<str
         slotKeys
     );
 
+    // Same explanation the list shows, so a reader switching view modes does
+    // not lose the reason a card is in front of them.
+    const { terms, offSlot } = useSearchExplanation(
+        entity,
+        collection.properties as Record<string, unknown>,
+        [slotKeys.titleKey, slotKeys.subtitleKey],
+        searchString
+    );
+
     const handleClick = (e?: React.MouseEvent) => {
         // Cmd+click (Mac) or Ctrl+click (Windows) toggles selection
         if (e && (e.metaKey || e.ctrlKey) && selectionEnabled) {
@@ -152,7 +166,9 @@ export function EntityCardBinding<M extends Record<string, unknown> = Record<str
                 {/* Title slot */}
                 <div className="truncate my-1 text-sm font-medium min-h-[20px]">
                     {slots.title ? (
-                        <SlotValue slot={slots.title} size="small"/>
+                        terms.length > 0 && typeof slots.title.value === "string"
+                            ? <Highlighted text={slots.title.value} terms={terms}/>
+                            : <SlotValue slot={slots.title} size="small"/>
                     ) : (
                         <Typography variant="body2" className="text-surface-500">
                             {entity.id}
@@ -160,10 +176,19 @@ export function EntityCardBinding<M extends Record<string, unknown> = Record<str
                     )}
                 </div>
 
-                {/* Subtitle slot */}
-                {slots.subtitle && (
+                {/* Subtitle slot — or, while searching, where the hit was. A
+                    card whose match is in a field it does not show looks as
+                    arbitrary as a list row does. */}
+                {offSlot ? (
+                    <MatchExplanation
+                        match={offSlot}
+                        label={fieldLabel(collection.properties as Record<string, unknown>, offSlot.field)}
+                    />
+                ) : slots.subtitle && (
                     <div className="line-clamp-3 [&_div]:line-clamp-3 text-xs text-surface-600 dark:text-surface-400 [&_p]:!my-1 [&_p:first-child]:!mt-0 [&_p:last-child]:!mb-0">
-                        <SlotValue slot={slots.subtitle} size="small"/>
+                        {terms.length > 0 && typeof slots.subtitle.value === "string"
+                            ? <Highlighted text={slots.subtitle.value} terms={terms}/>
+                            : <SlotValue slot={slots.subtitle} size="small"/>}
                     </div>
                 )}
 
@@ -190,10 +215,20 @@ export function EntityCardBinding<M extends Record<string, unknown> = Record<str
                     </div>
                 )}
 
-                {/* Status slot */}
-                {slots.status && (
-                    <div className="mt-1">
-                        <SlotValue slot={slots.status} size="small"/>
+                {/* Status + tags slot — "free chips beside the status" */}
+                {(slots.status || slots.tags) && (
+                    <div className="flex items-center gap-1 mt-1 flex-wrap">
+                        {slots.status && <SlotValue slot={slots.status} size="small"/>}
+                        {slots.tags && <TagChips slot={slots.tags}/>}
+                    </div>
+                )}
+
+                {/* Date slot — a card is a list row with the image on top, and the
+                    row has always shown it. It was the one slot the card resolved
+                    and never rendered. */}
+                {slots.date && (
+                    <div className="mt-1 text-[10px] text-surface-500 dark:text-surface-400">
+                        {slots.date.formatted}
                     </div>
                 )}
             </div>

package/src/components/CollectionViewBinding/SearchExplanation.tsx

@@ -0,0 +1,106 @@
+import React, { useMemo } from "react";
+import type { SearchMatch } from "@rebasepro/types";
+import { Snippet, searchTerms, offSlotMatch, localRowMatch } from "./SearchHighlight";
+
+/**
+ * The one place a view asks "why is this row here?" and gets something to draw.
+ *
+ * List, cards and board all render the same title-and-subtitle slots over the
+ * same machinery. An explanation that shows up in one of them and not the others
+ * reads as randomness rather than as a feature, so the decision and the markup
+ * live here and each view calls them.
+ */
+
+/**
+ * Terms to mark inside values the row already shows, plus the single match
+ * worth putting where the subtitle would go — or nothing, when the row is not
+ * the product of a search or the hit is already visible.
+ *
+ * Prefers the server's `_matches`, which knows the stemming the index used, and
+ * falls back to reading the row directly. That fallback is not belt-and-braces:
+ * rows reach the panel over REST, the realtime socket and the offline cache,
+ * and only one of those carries query metadata.
+ */
+export function useSearchExplanation(
+    entity: { values?: Record<string, unknown>; searchMatches?: SearchMatch[] },
+    properties: Record<string, unknown> | undefined,
+    shownKeys: (string | undefined)[],
+    searchString: string | undefined
+): { terms: string[]; offSlot: SearchMatch | undefined } {
+    const terms = useMemo(() => searchTerms(searchString), [searchString]);
+
+    // Joined so the memo compares by value: the caller builds this array inline,
+    // so its identity changes every render and would defeat the memo entirely.
+    //
+    // `|` is the separator because a property path is identifiers and dots — it
+    // cannot contain one, so the round trip is lossless. (A NUL would also be
+    // unambiguous and is what this first used; a raw control byte in a source
+    // file makes grep treat the whole file as binary, and the repo rejects it.)
+    const shownKey = shownKeys.map(k => k ?? "").join("|");
+
+    const offSlot = useMemo(
+        () => {
+            if (terms.length === 0) return undefined;
+            const shown = shownKey.split("|").map(k => k || undefined);
+            return offSlotMatch(entity.searchMatches, shown)
+                ?? localRowMatch(entity.values, properties, terms, shown);
+        },
+        [entity.searchMatches, entity.values, properties, shownKey, terms]
+    );
+
+    return { terms, offSlot };
+}
+
+/**
+ * Which field the hit was in, and the text around it.
+ *
+ * Sits where the subtitle would have gone. Deliberately quiet — a small amber
+ * caption and one line — because it is context for a result, not the result. It
+ * has to survive a narrow column, so it truncates rather than wraps.
+ */
+export function MatchExplanation({ match, label }: { match: SearchMatch; label: string }) {
+    return (
+        <div className="mt-0.5 flex items-baseline gap-1.5 min-w-0">
+            <span
+                className="shrink-0 text-[10px] uppercase tracking-wide font-semibold text-amber-700 dark:text-amber-500/90"
+                title={match.field}
+            >
+                {label}
+            </span>
+            <span className="truncate text-xs text-surface-500 dark:text-surface-400 min-w-0">
+                <Snippet text={match.snippet}/>
+            </span>
+        </div>
+    );
+}
+
+/**
+ * What to call a matched field on screen.
+ *
+ * The path is what the config and the server speak — `questionnaire.
+ * certifications` — and is unreadable in a list. Resolve it to the property's
+ * declared `name`, walking into `map` properties for a dotted path, and fall
+ * back to the last segment humanised, so an unnamed field still reads as words
+ * rather than as a path.
+ */
+export function fieldLabel(properties: Record<string, unknown> | undefined, path: string): string {
+    const segments = path.split(".");
+    let node = properties;
+    let named: string | undefined;
+
+    for (const segment of segments) {
+        const property = node?.[segment] as { name?: string; properties?: Record<string, unknown> } | undefined;
+        // A path can run deeper than the schema describes — `content.value`,
+        // where `content` is an array of blocks whose shape is not declared
+        // property-by-property. Keep the last name that *was* declared rather
+        // than discarding it: "Content" is the answer a reader wants, and
+        // resetting to undefined here labelled that field "Value".
+        if (!property) break;
+        named = property.name ?? named;
+        node = property.properties;
+    }
+
+    if (named) return named;
+    const last = segments[segments.length - 1] ?? path;
+    return last.replace(/[_-]+/g, " ").replace(/^./, c => c.toUpperCase());
+}

package/src/components/CollectionViewBinding/SearchHighlight.tsx

@@ -0,0 +1,311 @@
+import React, { useMemo } from "react";
+import type { SearchMatch } from "@rebasepro/types";
+
+/**
+ * Showing a searcher *why* a row is in their results.
+ *
+ * A ranked list answers "which rows" and never "why this one". When the term is
+ * in the title that is self-evident; when it is in a field the list does not
+ * show — a certification, a nested answer, a note — the row looks arbitrary and
+ * the only way to find out is to open it. That is the whole reason this exists.
+ *
+ * Two jobs, and they are deliberately separate:
+ *
+ * 1. {@link Highlighted} marks the term inside a value the list already shows.
+ * 2. {@link offSlotMatch} finds a match in a field that has no slot, so the
+ *    caller can put it where the subtitle would have gone.
+ */
+
+/** `<mark>` is Postgres's delimiter, and what `ts_headline` emits. */
+const MARK = /(<mark>.*?<\/mark>)/g;
+
+/**
+ * Render a `ts_headline` snippet: text with `<mark>` around each hit.
+ *
+ * Split-and-render rather than `dangerouslySetInnerHTML`. The text around the
+ * marks is whatever a user typed into their own record, and the only markup it
+ * is allowed to carry is the highlight Postgres put there. Anything else stays
+ * inert text.
+ */
+/**
+ * Context kept before and after a hit, in characters.
+ *
+ * Asymmetric on purpose. The snippet renders on one truncated line, so anything
+ * before the hit competes with the hit itself for the width available — with a
+ * generous lead-in the mark is pushed off the right edge and the reader sees a
+ * fragment with nothing highlighted in it, which is worse than no snippet at
+ * all. Lead with just enough to not start abruptly, then run on.
+ */
+const SNIPPET_LEAD = 16;
+const SNIPPET_TRAIL = 90;
+
+/**
+ * Pull the first mark near the front of the snippet.
+ *
+ * The snippet renders on one truncated line whose width is not knowable here —
+ * a list column is wide, the same list beside an open record is not. Whatever
+ * precedes the mark competes with it for that width, and when the mark loses
+ * the reader gets a fragment of their record with nothing highlighted in it,
+ * which reads as the feature being broken rather than as a narrow column.
+ *
+ * `ts_headline` centres its fragment on the match, so roughly half the window
+ * is lead-in; that is the right shape for a paragraph and the wrong one for a
+ * line. Trimming here rather than asking Postgres for a smaller window keeps
+ * the trailing context, which is what actually explains the hit — and applies
+ * the same shape to the snippets built in the browser, so a row looks the same
+ * whichever path produced it.
+ */
+export function trimSnippetLead(text: string, lead: number = SNIPPET_LEAD): string {
+    const at = text.indexOf("<mark>");
+    if (at < 0 || at <= lead) return text;
+    // Trim the lead-in only. Running the word-boundary strip over the whole
+    // remainder eats the mark itself when the lead is short enough that the
+    // slice opens on `<mark>`, which has no space in it to stop at.
+    const head = text.slice(at - lead, at).replace(/^\S*\s/, "");
+    return "…" + head + text.slice(at);
+}
+
+export function Snippet({ text, className }: { text: string; className?: string }) {
+    const parts = useMemo(() => trimSnippetLead(text).split(MARK), [text]);
+    return (
+        <span className={className}>
+            {parts.map((part, i) =>
+                part.startsWith("<mark>")
+                    ? (
+                        <mark
+                            key={i}
+                            className="bg-amber-200/70 dark:bg-amber-400/30 text-inherit rounded-[3px] px-[1px]"
+                        >
+                            {part.slice(6, -7)}
+                        </mark>
+                    )
+                    : <React.Fragment key={i}>{part}</React.Fragment>
+            )}
+        </span>
+    );
+}
+
+/**
+ * Mark every occurrence of the searched terms inside a plain value.
+ *
+ * Used for values the list already renders, where the server's snippet would be
+ * the wrong thing to show: the snippet is truncated to a fragment and folded to
+ * the indexed form, while the cell should keep the record's real text. So the
+ * terms are re-matched here, on the display value.
+ *
+ * Deliberately dumber than the server's matching, and it has to be: this cannot
+ * stem or unaccent without reimplementing the text search configuration in the
+ * browser and getting it subtly different. It marks what it can find as a
+ * prefix, case- and accent-insensitively, and marks nothing when it cannot —
+ * a highlight that is merely absent reads as "no hit in this field", which is
+ * the honest answer for a stem the browser cannot reproduce.
+ */
+export function Highlighted({ text, terms, className }: { text: string; terms: string[]; className?: string }) {
+    const segments = useMemo(() => splitOnTerms(text, terms), [text, terms]);
+    if (segments.length <= 1) return <span className={className}>{text}</span>;
+    return (
+        <span className={className}>
+            {segments.map((seg, i) =>
+                seg.hit
+                    ? (
+                        <mark
+                            key={i}
+                            className="bg-amber-200/70 dark:bg-amber-400/30 text-inherit rounded-[3px] px-[1px]"
+                        >
+                            {seg.text}
+                        </mark>
+                    )
+                    : <React.Fragment key={i}>{seg.text}</React.Fragment>
+            )}
+        </span>
+    );
+}
+
+/** Strip diacritics so `gestion` marks `gestión`, mirroring the index's unaccent. */
+const fold = (value: string): string =>
+    value.normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase();
+
+interface Segment { text: string; hit: boolean }
+
+/**
+ * Split `text` into hit / non-hit runs.
+ *
+ * Matches on the *folded* form but slices the original, so the marked text
+ * keeps its accents and case — `Gestión`, not `gestion`. Folding is
+ * length-preserving for the diacritics this handles, which is what makes the
+ * indices transferable; a fold that changed length would misalign the slices.
+ */
+export function splitOnTerms(text: string, terms: string[]): Segment[] {
+    const haystack = fold(text);
+    const needles = terms.map(fold).filter(t => t.length >= 2);
+    if (needles.length === 0) return [{ text, hit: false }];
+
+    // Word-start matches only. A search for "iso" marking the "iso" inside
+    // "revisor" is noise, and reads as a bug rather than a feature.
+    const bounds: [number, number][] = [];
+    for (const needle of needles) {
+        let from = 0;
+        for (;;) {
+            const at = haystack.indexOf(needle, from);
+            if (at === -1) break;
+            const before = at === 0 ? " " : haystack[at - 1];
+            if (!/[\p{L}\p{N}]/u.test(before)) bounds.push([at, at + needle.length]);
+            from = at + needle.length;
+        }
+    }
+    if (bounds.length === 0) return [{ text, hit: false }];
+
+    // Merge overlaps so two terms hitting the same run mark it once.
+    bounds.sort((a, b) => a[0] - b[0]);
+    const merged: [number, number][] = [];
+    for (const [start, end] of bounds) {
+        const last = merged[merged.length - 1];
+        if (last && start <= last[1]) last[1] = Math.max(last[1], end);
+        else merged.push([start, end]);
+    }
+
+    const segments: Segment[] = [];
+    let cursor = 0;
+    for (const [start, end] of merged) {
+        if (start > cursor) segments.push({ text: text.slice(cursor, start), hit: false });
+        segments.push({ text: text.slice(start, end), hit: true });
+        cursor = end;
+    }
+    if (cursor < text.length) segments.push({ text: text.slice(cursor), hit: false });
+    return segments;
+}
+
+/**
+ * The terms a searcher typed, as things to look for in a rendered value.
+ *
+ * Quoted phrases stay whole; `-excluded` terms are dropped, since marking a
+ * word the user asked *not* to see would be actively wrong. `websearch_to_tsquery`
+ * reads the same syntax on the server.
+ */
+export function searchTerms(searchString: string | undefined): string[] {
+    if (!searchString) return [];
+    const terms: string[] = [];
+    for (const [, phrase, bare] of searchString.matchAll(/"([^"]+)"|(\S+)/g)) {
+        const term = phrase ?? bare;
+        if (!term || term.startsWith("-")) continue;
+        if (/^(or|and)$/i.test(term)) continue;
+        terms.push(term);
+    }
+    return terms;
+}
+
+/**
+ * The best match to show when the term is nowhere the list already displays.
+ *
+ * `shownKeys` are the property paths the row is already rendering, so a match
+ * there needs no explaining — {@link Highlighted} marks it in place and the
+ * subtitle keeps its own job. Anything else is invisible, and one of those is
+ * what the subtitle slot gets replaced with.
+ *
+ * The first such match wins, and the server returns them in the order the
+ * collection declared its `search` fields — so the field an author put first is
+ * the one a reader sees, rather than whichever the database aggregated first.
+ */
+export function offSlotMatch(
+    matches: SearchMatch[] | undefined,
+    shownKeys: (string | undefined)[]
+): SearchMatch | undefined {
+    if (!matches || matches.length === 0) return undefined;
+    const shown = new Set(shownKeys.filter((k): k is string => Boolean(k)));
+    return matches.find(m => !shown.has(m.field));
+}
+
+// ── Finding the match locally ───────────────────────────────────────────────
+
+/**
+ * Where a search term appears in a row, computed from the row itself.
+ *
+ * The server can say this too — `_matches`, from `ts_headline` — and its answer
+ * is better, because it knows the stemming the index used. This exists because
+ * the admin cannot rely on getting it: rows reach the panel over three
+ * different transports (REST, the realtime socket, the offline cache) and only
+ * one of them carries query metadata. A feature that explains a result on some
+ * loads and not others is worse than one that always gives a slightly simpler
+ * answer.
+ *
+ * So: use the server's when it is there, fall back to this. Both produce the
+ * same `{ field, snippet }` shape, and this one marks with the same `<mark>`.
+ */
+export function localRowMatch(
+    values: Record<string, unknown> | undefined,
+    properties: Record<string, unknown> | undefined,
+    terms: string[],
+    shownKeys: (string | undefined)[]
+): SearchMatch | undefined {
+    if (!values || !properties || terms.length === 0) return undefined;
+    const shown = new Set(shownKeys.filter((k): k is string => Boolean(k)));
+
+    // Declared order, so the field an author put first wins — the same rule the
+    // server's `_matches` follows.
+    for (const [key, property] of Object.entries(properties)) {
+        if (shown.has(key)) continue;
+        const found = findInValue(values[key], terms, key, property as { type?: string });
+        if (found) return found;
+    }
+    return undefined;
+}
+
+function findInValue(
+    value: unknown,
+    terms: string[],
+    path: string,
+    property: { type?: string } | undefined
+): SearchMatch | undefined {
+    // An enum renders as a chip from a fixed vocabulary; marking inside one
+    // reads as noise, and `where` is the right tool for those anyway.
+    if (property && "enum" in property && property.enum) return undefined;
+
+    if (typeof value === "string") {
+        const snippet = snippetAround(value, terms);
+        return snippet ? { field: path, snippet } : undefined;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const found = findInValue(item, terms, path, undefined);
+            if (found) return found;
+        }
+        return undefined;
+    }
+    if (value && typeof value === "object") {
+        // Nested maps: report the path the author would recognise, which is the
+        // dotted one the `search` block uses.
+        for (const [key, nested] of Object.entries(value as Record<string, unknown>)) {
+            const found = findInValue(nested, terms, `${path}.${key}`, undefined);
+            if (found) return found;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * The text around the first hit, with every hit in view marked.
+ *
+ * Trimmed to a readable window rather than the whole field: a match in a long
+ * body should show the sentence it is in, not the first line of the document,
+ * and certainly not the document.
+ */
+export function snippetAround(text: string, terms: string[]): string | undefined {
+    const segments = splitOnTerms(text, terms);
+    const firstHit = segments.findIndex(s => s.hit);
+    if (firstHit === -1) return undefined;
+
+    const before = segments.slice(0, firstHit).map(s => s.text).join("");
+    const head = before.length > SNIPPET_LEAD
+        // Start at a word boundary so the snippet does not open mid-word.
+        ? "…" + before.slice(before.length - SNIPPET_LEAD).replace(/^\S*\s/, "")
+        : before;
+
+    let out = head;
+    for (let i = firstHit; i < segments.length; i++) {
+        const seg = segments[i];
+        out += seg.hit ? `<mark>${seg.text}</mark>` : seg.text;
+        // Enough context after the hit to read it, then stop.
+        if (out.length > head.length + SNIPPET_TRAIL) { out += "…"; break; }
+    }
+    return out.trim();
+}