@indxsearch/intrface 3.12.0 → 3.13.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 3.13.0
+
+### Minor Changes
+
+- SearchResults takes `showScore`, to show or hide each result's score from code. Given, it wins over the toggle in SearchSettingsPanel; left out, the toggle decides, as before.
+
+### Patch Changes
+
+- bac9b80: SearchField has a built-in Clear button. It shows while the field holds text and puts the focus back in the field. Turn it off with `clearable={false}`. SearchInput keeps its own Clear, which also resets the filters.
+- Updated dependencies [ffda712]
+- Updated dependencies
+- Updated dependencies [bac9b80]
+- Updated dependencies
+- Updated dependencies [f1bb38b]
+  - @indxsearch/systm@2.21.0
+
 ## 3.12.0
 
 ### Minor Changes

package/dist/components/AskPanel.d.ts

@@ -0,0 +1,43 @@
+import { default as React } from 'react';
+import { AskSource, AskStatus, AskFilters } from '../hooks/useAsk';
+export interface AskPanelProps {
+    /** The question to answer. A new value asks it and starts a new conversation; null or empty
+     *  shows nothing. To ask the same text again, give the panel a new `key`. */
+    question: string | null;
+    /** Lets the visitor ask follow-up questions under the answer. Each is answered with the
+     *  conversation so far (the server uses the last three turns), and the earlier turns stay on
+     *  screen above it. */
+    followUps?: boolean;
+    /** Called when the visitor picks a cited source. Look the record up by its documentKey. */
+    onSourceClick?: (source: AskSource) => void;
+    /** The label over each answer. Default "Answer". */
+    label?: string;
+    /** Renders the answer text, for a page with a markdown renderer of its own. `cite(n)` gives the
+     *  citation mark for source n. Default: intrface's own markdown (paragraphs, headings, lists,
+     *  code blocks, inline code, bold, italics, links), with [n] as citation marks. */
+    renderAnswer?: (answer: string, cite: (n: number) => React.ReactNode) => React.ReactNode;
+    /** Shown under the answer as "Ask a follow-up" when `followUps` is off: e.g. back to the
+     *  search field. With `followUps` on, that button goes to the follow-up field instead. */
+    onFollowUp?: () => void;
+    /** On a catalogue, called with the filters a description was searched with, as soon as they are
+     *  known: give them to `useFilterSuggestion().apply` so the page's list shows the same set. */
+    onFilters?: (filters: AskFilters) => void;
+    /** How a filter reads on its chip. Default: a text value as itself, a yes/no by its field's
+     *  name, a range by its bounds. */
+    filterLabel?: (filter: AskFilters['filters'][number]) => string;
+    /** Told when the answer starts and stops streaming, e.g. to show a Stop button elsewhere. */
+    onStatusChange?: (status: AskStatus) => void;
+    /** Fills the height its container gives it, for a panel beside the results: the conversation
+     *  scrolls on its own, the follow-up field stays at the bottom, and the view follows an answer
+     *  as it streams while the visitor is at the end of it. Give the container a height (or make it
+     *  a flex child that has one). Without it the panel is as tall as its content. */
+    fill?: boolean;
+    className?: string;
+}
+/**
+ * An answer to a question, written from the dataset's records by Search or ask: the question, the
+ * answer as it streams, the sources it cites, and what to do when it fails or is limited. With
+ * `followUps`, a conversation: a field under the answer asks the next question with the earlier
+ * ones as context. Pair it with `SearchInput`'s `onAsk`, or `useSearchOrAsk` (when to offer).
+ */
+export declare const AskPanel: React.FC<AskPanelProps>;

package/dist/components/SearchInput.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 import { InputSize } from '@indxsearch/systm';
+import { SearchOrAskState } from '../hooks/useSearchOrAsk';
 export interface SearchInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
     inputSize?: InputSize;
     /** One Clear button that resets the query and the filters, shown whenever there is either. */
@@ -8,5 +9,16 @@ export interface SearchInputProps extends React.InputHTMLAttributes<HTMLInputEle
     /** Chips that say what the search is doing: the number of active filters, "Nearest" when no
      *  result reached the coverage bar, and "No results". */
     showStatus?: boolean;
+    /** Search or ask: when given, and the dataset has it switched on, an offer to ask appears in
+     *  the chip row while the visitor types something an answer would serve. A strong offer also
+     *  makes Enter ask. Called with the text to ask; show the answer with `AskPanel`. */
+    onAsk?: (text: string) => void;
+    /** The offer, when the page runs `useSearchOrAsk` itself (to show it elsewhere too, or to use
+     *  `describes`): the field then shows this one and does not judge again. */
+    searchOrAsk?: SearchOrAskState;
+    /** Where the offer to ask shows. `chip` (default): a button in the field's chip row. `below`: a
+     *  row of its own under the field, as on the Indx docs: a full-size button and an Enter hint.
+     *  The row keeps its height while Search or ask is on, so an offer appearing moves nothing under it. */
+    askOffer?: 'chip' | 'below';
 }
 export declare const SearchInput: React.FC<SearchInputProps>;

package/dist/components/SearchResults.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 import { SearchResult as SearchResultData } from '../context/SearchContext';
+import { SearchOrAskState } from '../hooks/useSearchOrAsk';
 export interface SearchResultsProps {
     fields?: string[];
     resultsPerPage?: number;
@@ -16,6 +17,17 @@ export interface SearchResultsProps {
      * result, so the dataset's statistics get click-through and click position.
      */
     children: (item: Record<string, any>, meta: SearchResultMeta) => React.ReactNode;
+    /**
+     * The offer, when the page runs `useSearchOrAsk`: while it is strong and the dataset has the
+     * rule on, the list shows coverage hits only (up to the truncation point), and nothing when
+     * nothing is confirmed, so the offer stands alone. Without it the list is never cut.
+     */
+    searchOrAsk?: SearchOrAskState;
+    /**
+     * Shows each result's score beside it. Given, it wins over the `showScore` search setting (the
+     * toggle in SearchSettingsPanel); left out, that setting decides, and it is on by default.
+     */
+    showScore?: boolean;
 }
 export interface SearchResultMeta {
     result: SearchResultData;

package/dist/context/SearchContext.d.ts

@@ -63,6 +63,11 @@ export interface SearchContextType {
     authErrorInfo?: SearchErrorInfo;
     retry?: () => void;
     allowEmptySearch: boolean;
+    facetsEnabled: boolean;
+    datasetBounds: Record<string, {
+        min: number;
+        max: number;
+    }>;
     url: string;
     team: string;
     dataset: string;
@@ -82,7 +87,19 @@ export interface SearchContextType {
     fetchMoreResults: (newMax: number) => void;
     selectResult?: (result: SearchResult) => Promise<void>;
     sessionId?: string;
+    source?: string;
+    count?: boolean;
+    /** What the search runs on: `state.query`, or what `searchTextOf` or a registered rewrite made of it. */
+    searchText?: string;
+    /** Searches the typed text as it is, this once: the way back from a rewrite ("Search for your exact words"). */
+    searchAsTyped?: () => void;
+    /** Registers what the search runs on for what is typed, for a hook inside the provider
+     *  (useSearchOrAsk's Ask phrases); null takes it off. The provider's own `searchTextOf` wins. */
+    setSearchRewrite?: (rewrite: ((typed: string) => string) | null) => void;
 }
+/** The field's placeholder unless the page sets one. SearchInput says "Search or ask" instead
+ *  while asking is on, so it must know this one from a page's own. */
+export declare const DEFAULT_PLACEHOLDER = "Type to search";
 export declare const SearchContext: React.Context<SearchContextType | undefined>;
 export declare const SearchProvider: React.FC<{
     children: React.ReactNode;
@@ -101,5 +118,10 @@ export declare const SearchProvider: React.FC<{
     preAuthenticatedToken?: string;
     source?: string;
     count?: boolean;
+    /** The text to search for what is typed, when it is not the typed text itself: the field keeps
+     *  showing what the visitor typed, and the search runs on this. Search or ask's Ask phrases use
+     *  it ("help me find the movie about the green ogre" searches "green ogre"). Called on every
+     *  render with the typed text; return it unchanged to search it as typed. */
+    searchTextOf?: (typed: string) => string;
 }>;
 export declare const useSearchContext: () => SearchContextType;

package/dist/context/useSearchExecution.d.ts

@@ -15,9 +15,11 @@ export interface UseSearchExecutionOptions {
     sessionId: string;
     source?: string;
     count: boolean;
+    /** The text to search for what is typed (SearchProvider's `searchTextOf`). Absent: the typed text. */
+    searchTextOf?: (typed: string) => string;
 }
 export interface UseSearchExecutionResult {
     /** Runs the last search again, after a failure. */
     retrySearch: () => void;
 }
-export declare function useSearchExecution({ state, setState, authenticatedFetch, auth, url, team, dataset, allowEmptySearch, facetsEnabled, enableDebugLogs, shouldFetchMore, sessionId, source, count, }: UseSearchExecutionOptions): UseSearchExecutionResult;
+export declare function useSearchExecution({ state, setState, authenticatedFetch, auth, url, team, dataset, allowEmptySearch, facetsEnabled, enableDebugLogs, shouldFetchMore, sessionId, source, count, searchTextOf, }: UseSearchExecutionOptions): UseSearchExecutionResult;

package/dist/hooks/useAsk.d.ts

@@ -0,0 +1,89 @@
+/** A record the answer may use, numbered as the answer cites it ([n]). */
+export interface AskSource {
+    n: number;
+    documentKey: number;
+    title: string;
+}
+/** An earlier question and its answer, sent with a follow-up so the answer can build on it. */
+export interface AskTurn {
+    question: string;
+    answer: string;
+    /** On a catalogue, the list that turn put on the page: a follow-up is about it. */
+    shown?: {
+        filters: AskFilters['filters'];
+        text: string;
+        sort?: AskFilters['sort'];
+    };
+}
+export type AskStatus = 'idle' | 'searching' | 'writing' | 'answered' | 'error' | 'limited';
+export interface AskState {
+    question: string;
+    status: AskStatus;
+    /** The answer as written so far, citing sources as [n]. */
+    answer: string;
+    sources: AskSource[];
+    /** Why it failed, when status is 'error': the server's code (nothingFound, upstreamBusy, failed,
+     *  or an HTTP problem code) and a sentence for the page. */
+    error?: {
+        code: string;
+        message: string;
+    };
+    /** When status is 'limited': seconds until asking again may succeed. */
+    retryAfterSeconds?: number;
+    /** The server's id for this ask (Indx-Ask-Id). A source opened is reported against it. */
+    askId?: string;
+    /** On a catalogue, a description's filters, as the server searched with them, and what it found. */
+    filters?: AskFilters;
+    /** What the agent has done so far ("Searching: Folkehøyskole, by Elevtall"), while it works. */
+    steps: string[];
+}
+/** What a catalogue's description was searched with: filters, words no filter covers, and the count. */
+export interface AskFilters {
+    filters: {
+        field: string;
+        value?: string | null;
+        min?: number | null;
+        max?: number | null;
+    }[];
+    text: string;
+    /** An order the description asked for ("the largest"): a Sortable field. */
+    sort?: {
+        field: string;
+        descending: boolean;
+    } | null;
+    found: number;
+    /** True when the count is a cap: there are more. */
+    more: boolean;
+}
+/**
+ * Asks the dataset a question (`search-or-ask/ask`) and follows the answer as it streams: the
+ * sources first, then the text, then done. One question at a time; asking again, or `stop`, ends
+ * the one in flight and keeps what had arrived. The answer uses the dataset's records and nothing
+ * else, and says so when they do not hold it.
+ */
+export declare function useAsk(): {
+    ask: (question: string, history?: AskTurn[]) => Promise<void>;
+    stop: () => void | undefined;
+    reset: () => void;
+    openSource: (source: AskSource, ofAsk?: string) => Promise<void>;
+    busy: boolean;
+    question: string;
+    status: AskStatus;
+    /** The answer as written so far, citing sources as [n]. */
+    answer: string;
+    sources: AskSource[];
+    /** Why it failed, when status is 'error': the server's code (nothingFound, upstreamBusy, failed,
+     *  or an HTTP problem code) and a sentence for the page. */
+    error?: {
+        code: string;
+        message: string;
+    };
+    /** When status is 'limited': seconds until asking again may succeed. */
+    retryAfterSeconds?: number;
+    /** The server's id for this ask (Indx-Ask-Id). A source opened is reported against it. */
+    askId?: string;
+    /** On a catalogue, a description's filters, as the server searched with them, and what it found. */
+    filters?: AskFilters;
+    /** What the agent has done so far ("Searching: Folkehøyskole, by Elevtall"), while it works. */
+    steps: string[];
+};

package/dist/hooks/useFilterSuggestion.d.ts

@@ -0,0 +1,42 @@
+import { SearchOrAskState } from './useSearchOrAsk';
+/** One filter a description asked for: a value (text, or "true"/"false") or a number range. */
+export interface FilterSuggestion {
+    field: string;
+    value?: string | null;
+    min?: number | null;
+    max?: number | null;
+}
+export interface FilterSuggestionResult {
+    filters: FilterSuggestion[];
+    /** What no filter covers, to search for; empty when the filters cover it all. */
+    text: string;
+    /** An order the description asked for, on a Sortable field. */
+    sort?: {
+        field: string;
+        descending: boolean;
+    } | null;
+}
+export declare function localFilters(text: string, facets: Record<string, {
+    key: string;
+}[]> | null | undefined): FilterSuggestionResult | null;
+export interface UseFilterSuggestionOptions {
+    /** The offer from `useSearchOrAsk`. With it, a description is turned into filters while the
+     *  visitor types, the way the dataset's `filtersWhileTyping` says: facet values at once, the
+     *  model for the rest, or nothing until Ask. */
+    auto?: SearchOrAskState;
+}
+/**
+ * Search or ask on a catalogue: turns a description of what to list ("private videregående i
+ * bergen") into filters on the dataset's own fields (`search-or-ask/filters`), and applies them
+ * to the search, where ActiveFiltersPanel shows them and the visitor can remove each. Ask for it
+ * when `useSearchOrAsk` says `describes`, or hand it the offer (`auto`) and it acts on its own.
+ */
+export declare function useFilterSuggestion(options?: UseFilterSuggestionOptions): {
+    suggestion: FilterSuggestionResult | null;
+    forText: string;
+    loading: boolean;
+    suggest: (text: string) => Promise<void>;
+    apply: (result: FilterSuggestionResult) => void;
+    clear: () => void;
+    appliedText: string | null;
+};

package/dist/hooks/useSearchOrAsk.d.ts

@@ -0,0 +1,52 @@
+import { CutRule, Offer } from '../utils/searchOrAsk';
+export interface UseSearchOrAskOptions {
+    /** false keeps the hook quiet: no settings read, no judgement. Default true. */
+    enabled?: boolean;
+    /** The text to judge. Defaults to the search query of the surrounding SearchProvider. */
+    text?: string;
+    /** How long the visitor must pause before the server is asked. Default 300 ms. */
+    pauseMs?: number;
+}
+export interface SearchOrAskState {
+    /** True once the dataset's settings say Search or ask is on and the instance can run it. Until
+     *  then, and for good when it is off, the offer stays 'none' and nothing is sent. */
+    available: boolean;
+    /** What to show: nothing, a quiet "ask about this", or a strong offer where Enter asks. */
+    offer: Offer;
+    /** The latest probability from the server, for a readout; null before the first judgement. */
+    p: number | null;
+    /** The judge's reading of whether the top results could answer what is typed; null when it did not say. */
+    answerable: number | null;
+    /** The text the offer is about: what would be asked. */
+    text: string;
+    /** On a catalogue: the probability the visitor describes what to list. Null elsewhere. */
+    criteria: number | null;
+    /** On a catalogue: the text describes what to list, so it can become filters (useFilterSuggestion). */
+    describes: boolean;
+    /** The list should show coverage hits only: the offer is strong and the dataset has the rule on
+     *  (`cutWhileAsking`). SearchResults applies it when handed this state; `visibleResults` is the rule. */
+    cutResults: boolean;
+    /** The cut's two lines, the dataset's, for `visibleResults`. */
+    cutRule: CutRule;
+    /** The page's searches run with whole-word coverage: the offer is strong and the dataset has
+     *  that rule on. The hook sets and clears it on the search context itself. */
+    strictCoverage: boolean;
+    /** On a catalogue, what to do with a description while typing (the dataset's `filtersWhileTyping`):
+     *  'off' leaves the list until Ask, 'facets' applies typed facet values at once, 'model' also asks
+     *  the filters route for the rest. `useFilterSuggestion({ auto })` acts on it. */
+    filtersWhileTyping: 'off' | 'facets' | 'model';
+    /** The offer is for what is in the field now: the field still extends the text it was judged on.
+     *  Typing on from a question keeps it (the hook does not ask again while the text only grows);
+     *  backspacing into it, or changing it, does not, until the judge has read the new text. Show an
+     *  offer only while this holds, or it blinks out on every keystroke or lingers after a change. */
+    stands: boolean;
+}
+/**
+ * Decides, while the visitor types, whether to offer an answer beside the results. Reads the
+ * dataset's Search or ask settings once, then on each typing pause asks the server's judge
+ * (`search-or-ask/intent`) when the rules allow, keeps only the newest answer, and applies the
+ * dataset's thresholds with hysteresis. It never asks again while the text only grows and the
+ * offer is already strong. A failure of any kind leaves the offer at 'none': the search itself is
+ * never affected.
+ */
+export declare function useSearchOrAsk(options?: UseSearchOrAskOptions): SearchOrAskState;