@indxsearch/intrface 3.11.0 → 3.13.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # 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
+
+- 1533dad: SearchInput shows what the search is doing. A blue chip counts the active filters. A Nearest chip appears when nothing matched your words directly and the list holds the nearest results instead; its tooltip says so. A No results chip appears when a search returns nothing. There is one Clear button, and it now resets the query and the filters together, so it also shows on an empty search with filters set. `showStatus={false}` hides the chips.
+
+  SearchField leaves room for what sits on its right, such as a Clear button or chips, so typed text no longer runs underneath them.
+
+  The search icon lights up only while the input has focus. Clicking Clear used to light it for a moment.
+
+- 43b8279: SearchResults shows a failed search as a state the visitor can read, not as an error message. Each kind of failure has its own icon and a short line: the server can't be reached, the key was not accepted or has no access, the dataset doesn't exist, the dataset is getting ready, too many searches, or a server error. Under it, a small technical line tells whoever built the page what happened and what to do. Where trying again can help there is a Try again button, and a dataset that is still loading or indexing is retried by itself when the server says it is ready.
+
+  No results now shows nothing in the list, since SearchInput says it in the field.
+
+  For your own components, the context has `retry()`, and `authErrorInfo` and `state.errorInfo` next to the existing messages, with the kind of failure, whether retrying can help, and the technical line. `describeSearchError` classifies any error the same way, and `SearchResultsMessage` is the component SearchResults uses, if you want it elsewhere.
+
+  A key that cannot reach the dataset (403) used to be reported as a failed connection. The startup messages in `authError` now follow the same form as search errors, for example "Dataset status failed: HTTP 404".
+
+### Patch Changes
+
+- 383e0f5: Filter panels are calmer when something is wrong. A panel whose field isn't set up for it (not Filterable, or not Facetable for a value panel) no longer shows a red message: it keeps its title, says "Not available" in muted text, names the missing role in a small technical line, and tells the console what to change. When the search fails to start, the filter panels step aside instead of each reporting its field as broken or showing a loading skeleton that never ends; the results area explains the failure once.
+- Updated dependencies [f9400f4]
+- Updated dependencies [1533dad]
+  - @indxsearch/systm@2.20.0
+
 ## 3.11.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/FilterPanelNotice.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+export interface FilterPanelNoticeProps {
+    /** The panel's own title, so the notice sits where the panel would have been. */
+    label?: string;
+    field: string;
+    /** The roles the field lacks, such as ['filterable', 'facetable']. */
+    missing: string[];
+}
+/** A filter panel whose field cannot be used: the field is not marked for the role the panel needs.
+ *  A setup mistake, so it is said quietly in the panel and fully in the console, not in red. */
+export declare const FilterPanelNotice: React.FC<FilterPanelNoticeProps>;

package/dist/components/SearchInput.d.ts

@@ -1,8 +1,24 @@
 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. */
     showClear?: boolean;
     showFocus?: boolean;
+    /** 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/components/SearchResultsMessage.d.ts

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+import { SearchErrorInfo } from '../context/searchError';
+export interface SearchResultsMessageProps {
+    error: SearchErrorInfo;
+    /** Tries again. Shown as a button where retrying can help; a dataset that is getting ready is retried by itself. */
+    onRetry?: () => void;
+    /** Hides the technical line, for a page whose visitors should not see it. */
+    hideTechnical?: boolean;
+}
+/** What SearchResults shows in place of the list when a search fails: an icon, a line for the
+ *  visitor, the technical reason, and Try again where that can help. */
+export declare const SearchResultsMessage: React.FC<SearchResultsMessageProps>;

package/dist/context/SearchContext.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 import { CoverageSetup } from '@indxsearch/indx-types';
+import { SearchErrorInfo } from './searchError';
 import { ValueMatch, NumericRange } from './buildFilterProxy';
 export type { ValueMatch, NumericRange };
 export interface SearchSettings {
@@ -25,6 +26,7 @@ export interface SearchState {
     resultsSuppressed?: boolean;
     facetDebounceDelayMillis?: number;
     error?: string;
+    errorInfo?: SearchErrorInfo;
     facets?: any | null;
     filterableFields: string[];
     facetableFields: string[];
@@ -58,7 +60,14 @@ export interface SearchContextType {
     state: SearchState;
     isFetchingInitial: boolean;
     authError?: string;
+    authErrorInfo?: SearchErrorInfo;
+    retry?: () => void;
     allowEmptySearch: boolean;
+    facetsEnabled: boolean;
+    datasetBounds: Record<string, {
+        min: number;
+        max: number;
+    }>;
     url: string;
     team: string;
     dataset: string;
@@ -78,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;
@@ -97,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/searchError.d.ts

@@ -0,0 +1,37 @@
+/**
+ * What kind of failure stopped the search, so a component can show it to the visitor rather than
+ * print the error's text:
+ *
+ * - `unreachable` — no answer at all: the server is down, the URL is wrong, or the network is gone
+ * - `unauthorized` — 401, the key is invalid or has expired
+ * - `forbidden` — 403, the key does not reach this dataset
+ * - `notFound` — 404, no such team or dataset
+ * - `notReady` — 409 `invalidState` with `retryable`: loading or indexing, the same request succeeds soon
+ * - `unavailable` — 409 otherwise: the dataset is in a state search cannot use (Error, or a build in progress)
+ * - `rateLimited` — 429, too many requests for this key
+ * - `server` — 5xx
+ * - `setup` — SearchProvider was not given what it needs (url, team, dataset, token)
+ * - `unknown` — anything else
+ */
+export type SearchErrorKind = 'unreachable' | 'unauthorized' | 'forbidden' | 'notFound' | 'notReady' | 'unavailable' | 'rateLimited' | 'server' | 'setup' | 'unknown';
+export interface SearchErrorInfo {
+    kind: SearchErrorKind;
+    /** The error's own message, as `authError` and `state.error` carry it. */
+    message: string;
+    /** For whoever built the page: the status, the server's code and what to do. */
+    technical: string;
+    status?: number;
+    code?: string;
+    /** Seconds the server asked to wait (`Retry-After`), for `notReady` and `rateLimited`. */
+    retryAfterSeconds?: number;
+    /** Whether trying the same request again can succeed. */
+    retryable: boolean;
+}
+/** Thrown for a missing SearchProvider prop, so it is told apart from a failed request. */
+export declare class SearchSetupError extends Error {
+    constructor(message: string);
+}
+export declare function describeSearchError(err: unknown, where: {
+    team: string;
+    dataset: string;
+}): SearchErrorInfo;

package/dist/context/useIndxAuth.d.ts

@@ -1,8 +1,13 @@
+import { SearchErrorInfo } from './searchError';
 export interface IndxAuthResult {
     token: string | null;
     isFetchingInitial: boolean;
     /** Set when initialization failed (bad token, unknown dataset, unreachable server). */
     authError: string | null;
+    /** The same failure, classified: what kind it was, whether retrying can help, and a technical line. */
+    authErrorInfo: SearchErrorInfo | null;
+    /** Runs initialisation again, after a failure. */
+    retry: () => void;
     initialFacetStats: Record<string, {
         min: number;
         max: number;

package/dist/context/useSearchExecution.d.ts

@@ -15,6 +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 type UseSearchExecutionResult = void;
-export declare function useSearchExecution({ state, setState, authenticatedFetch, auth, url, team, dataset, allowEmptySearch, facetsEnabled, enableDebugLogs, shouldFetchMore, sessionId, source, count, }: UseSearchExecutionOptions): UseSearchExecutionResult;
+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, 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;