@perxel/spotlight 0.0.0-stage → 0.1.1

package/dist/core/storage.d.ts

@@ -0,0 +1,17 @@
+import type { PersistAdapter } from "../types.js";
+/**
+ * Keeps the conversation in `localStorage` under `key` for `days` after the visitor's last
+ * question. Private mode or blocked storage: the conversation just does not survive a reload.
+ */
+export declare function localStorageAdapter({ key, days }?: {
+    key?: string;
+    days?: number;
+}): PersistAdapter;
+/** Nowhere: the conversation lives as long as the page. */
+export declare const noPersist: PersistAdapter;
+/**
+ * What a question from the gate does: `none` (no conversation), `recent` (continues it) or
+ * `stale` (kept, but its last question is older than `continueHours`: a new one starts).
+ */
+export type ConversationState = "none" | "recent" | "stale";
+export declare function conversationState(persist: PersistAdapter, continueHours?: number): ConversationState;

package/dist/core/storage.js

@@ -0,0 +1,48 @@
+// The conversation kept in the browser. No React, no AI SDK: the gate asks whether there is a
+// conversation without loading the chat code.
+const DAY = 24 * 60 * 60 * 1000;
+/**
+ * Keeps the conversation in `localStorage` under `key` for `days` after the visitor's last
+ * question. Private mode or blocked storage: the conversation just does not survive a reload.
+ */
+export function localStorageAdapter({ key = "spotlight-chat", days = 7 } = {}) {
+    return {
+        read() {
+            try {
+                const raw = localStorage.getItem(key);
+                if (!raw)
+                    return null;
+                const v = JSON.parse(raw);
+                if (typeof v.id !== "string" || !Array.isArray(v.messages))
+                    return null;
+                if (!(Date.now() - v.savedAt < days * DAY)) {
+                    localStorage.removeItem(key);
+                    return null;
+                }
+                return v;
+            }
+            catch {
+                return null;
+            }
+        },
+        write(v) {
+            try {
+                if (v)
+                    localStorage.setItem(key, JSON.stringify(v));
+                else
+                    localStorage.removeItem(key);
+            }
+            catch {
+                // Storage blocked.
+            }
+        },
+    };
+}
+/** Nowhere: the conversation lives as long as the page. */
+export const noPersist = { read: () => null, write: () => { } };
+export function conversationState(persist, continueHours = 24) {
+    const v = persist.read();
+    if (!v?.messages.length)
+        return "none";
+    return Date.now() - v.savedAt < continueHours * 60 * 60 * 1000 ? "recent" : "stale";
+}

package/dist/gate/index.d.ts

@@ -0,0 +1,2 @@
+export { Gate, Marked, useGate, useGateContext, type GateApi, type UseGateOptions } from "./parts.js";
+export { useSearchAsk, type SearchAskOption, type UseSearchAskOptions } from "./useSearchAsk.js";

package/dist/gate/index.js

@@ -0,0 +1,5 @@
+// `@perxel/spotlight/gate`: the gate's headless parts and hooks (Radix dialog, the search engine).
+// Import it only from the gate module the provider loads lazily, so pages never load it until
+// the gate first opens (or is prefetched).
+export { Gate, Marked, useGate, useGateContext } from "./parts.js";
+export { useSearchAsk } from "./useSearchAsk.js";

package/dist/gate/parts.d.ts

@@ -0,0 +1,179 @@
+import { type ComponentPropsWithoutRef, type KeyboardEvent, type MouseEvent, type ReactNode } from "react";
+import { type ConversationState } from "../core/storage.js";
+import { type SearchDoc, type SearchIndex, type SearchResult, type Snippet } from "../core/search.js";
+import type { Action } from "../types.js";
+import { type SpotlightState } from "../react/provider.js";
+export interface UseGateOptions {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+/** Everything a gate needs, for a gate built from scratch. `Gate.Root` calls it and shares it with the parts. */
+export declare function useGate({ open, onOpenChange }: UseGateOptions): {
+    spotlight: SpotlightState;
+    mode: import("../types.js").SpotlightMode;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    copy: import("../types.js").SpotlightCopy;
+    query: string;
+    setQuery: import("react").Dispatch<import("react").SetStateAction<string>>;
+    typed: string;
+    index: SearchIndex | null;
+    conversation: ConversationState;
+    focused: boolean;
+    inputRef: import("react").RefObject<HTMLInputElement | null>;
+    search: {
+        results: SearchResult[];
+        groups: {
+            kind: string;
+            results: {
+                index: number;
+                doc: SearchDoc;
+                score: number;
+                titleMarks: [start: number, end: number][];
+                snippet?: Snippet;
+            }[];
+        }[];
+        open: boolean;
+        listed: boolean;
+        extras: {
+            doc: SearchDoc;
+            index: number;
+        }[];
+        active: number;
+        setActive: (i: number) => void;
+        onKeyDown: (e: KeyboardEvent<HTMLElement>) => boolean;
+        activate: (i: number) => void;
+        count: number;
+        inputProps: {
+            role: "combobox";
+            "aria-expanded": boolean;
+            "aria-controls": string | undefined;
+            "aria-autocomplete": "list";
+            "aria-activedescendant": string | undefined;
+        } | {
+            role?: undefined;
+            "aria-expanded"?: undefined;
+            "aria-controls"?: undefined;
+            "aria-autocomplete"?: undefined;
+            "aria-activedescendant"?: undefined;
+        };
+        listboxProps: {
+            id: string;
+            role: "listbox";
+        };
+        optionProps: (i: number) => import("./useSearchAsk.js").SearchAskOption;
+        askOptionProps: import("./useSearchAsk.js").SearchAskOption | null;
+    };
+    ask: (text: string) => void;
+    askable: boolean;
+    onOpen: (doc: SearchDoc) => void;
+    onLinkClick: (e: MouseEvent<HTMLAnchorElement>) => void;
+    /** What Enter does, for a hint by the field (`null`: nothing). */
+    hint: string | null;
+    /** The highlighted result's action, if it is one. */
+    activeAction: Action<any> | undefined;
+    actionFor: (doc: SearchDoc) => Action<any> | undefined;
+    kindLabel: (kind: string) => string;
+    /** Spread on the text field. */
+    inputProps: {
+        onKeyDown: (e: KeyboardEvent<HTMLInputElement>) => void;
+        placeholder: string;
+        "aria-label": string;
+        maxLength: number;
+        enterKeyHint: "search" | "send";
+        autoComplete: string;
+        autoCorrect: string;
+        spellCheck: boolean;
+        role: "combobox";
+        "aria-expanded": boolean;
+        "aria-controls": string | undefined;
+        "aria-autocomplete": "list";
+        "aria-activedescendant": string | undefined;
+        ref: import("react").RefObject<HTMLInputElement | null>;
+        value: string;
+        onChange: (e: {
+            target: {
+                value: string;
+            };
+        }) => void;
+        onFocus: () => void;
+        onBlur: () => void;
+    } | {
+        onKeyDown: (e: KeyboardEvent<HTMLInputElement>) => void;
+        placeholder: string;
+        "aria-label": string;
+        maxLength: number;
+        enterKeyHint: "search" | "send";
+        autoComplete: string;
+        autoCorrect: string;
+        spellCheck: boolean;
+        role?: undefined;
+        "aria-expanded"?: undefined;
+        "aria-controls"?: undefined;
+        "aria-autocomplete"?: undefined;
+        "aria-activedescendant"?: undefined;
+        ref: import("react").RefObject<HTMLInputElement | null>;
+        value: string;
+        onChange: (e: {
+            target: {
+                value: string;
+            };
+        }) => void;
+        onFocus: () => void;
+        onBlur: () => void;
+    };
+};
+export type GateApi = ReturnType<typeof useGate>;
+/** The gate's state, inside `Gate.Root`. */
+export declare function useGateContext(): GateApi;
+type DivProps = ComponentPropsWithoutRef<"div">;
+/**
+ * The gate: a modal dialog (Radix) with an overlay, the focus moved into the field on open and
+ * back where it was on close, Escape clearing a highlighted row before it closes, and a press on
+ * the content box itself (the gaps between pieces) closing it like a press outside.
+ * State: `data-state` (open/closed), `data-mode`, `data-has-results` on the content.
+ */
+declare function Root({ open, onOpenChange, children, overlayProps, ...props }: UseGateOptions & DivProps & {
+    overlayProps?: DivProps;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The text field. */
+declare function Input(props: ComponentPropsWithoutRef<"input">): import("react").JSX.Element;
+/** The listbox. Renders only while there are results; by default one `Gate.Item` per result. */
+declare function Results({ children, ...props }: Omit<DivProps, "children"> & {
+    children?: (result: SearchResult & {
+        index: number;
+    }) => ReactNode;
+}): import("react").JSX.Element | null;
+/**
+ * One result: a link for a document with a `url`, a button for an action. State:
+ * `data-highlighted` (the arrow keys' row; also `aria-selected`), `data-kind`. Children default to
+ * the marked title and the snippet or subtitle.
+ */
+declare function Item({ result, index, children, ...props }: {
+    result: SearchResult;
+    index: number;
+    children?: ReactNode;
+} & Omit<ComponentPropsWithoutRef<"a">, "children">): import("react").JSX.Element;
+/** Text with marked ranges in `<mark>` (style `mark[data-spotlight-mark]`). */
+export declare function Marked({ text, marks }: {
+    text: string;
+    marks: Snippet["marks"];
+}): import("react").JSX.Element;
+/** What Enter does, while it does something and the field has focus (`data-on`); children override the text. */
+declare function Hint({ children, ...props }: DivProps): import("react").JSX.Element;
+/** Closes the gate. */
+declare function Close(props: ComponentPropsWithoutRef<"button">): import("react").JSX.Element;
+/** Sends the typed text as a question (a send button for touch screens); only while there is text and Ask is on. */
+declare function Send(props: ComponentPropsWithoutRef<"button">): import("react").JSX.Element | null;
+export declare const Gate: {
+    Root: typeof Root;
+    Input: typeof Input;
+    Results: typeof Results;
+    Item: typeof Item;
+    Hint: typeof Hint;
+    Close: typeof Close;
+    Send: typeof Send;
+    Marked: typeof Marked;
+};
+export {};

package/dist/gate/parts.js

@@ -0,0 +1,282 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as Dialog from "@radix-ui/react-dialog";
+import { createContext, Fragment, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { conversationState } from "../core/storage.js";
+import { mergeCopy } from "../core/copy.js";
+import { buildIndex } from "../core/search.js";
+import { useSpotlight } from "../react/provider.js";
+import { useSearchAsk } from "./useSearchAsk.js";
+const ACTION_PREFIX = "action:";
+/** The action a search document opens, if any (`action:<id>`). */
+function actionFor(doc, actions) {
+    if (!doc.id.startsWith(ACTION_PREFIX))
+        return undefined;
+    const id = doc.id.slice(ACTION_PREFIX.length);
+    return actions.find((a) => a.id === id);
+}
+/** Actions with `search` as documents, unless the loaded index already holds one with that id. */
+function actionDocs(actions, docs) {
+    const have = new Set(docs.map((d) => d.id));
+    return actions
+        .filter((a) => a.search && !have.has(ACTION_PREFIX + a.id))
+        .map((a) => ({
+        id: ACTION_PREFIX + a.id,
+        kind: a.search.kind ?? "action",
+        title: a.search.title,
+        ...(a.search.subtitle ? { subtitle: a.search.subtitle } : {}),
+        ...(a.search.keywords ? { keywords: a.search.keywords } : {}),
+    }));
+}
+/** The search index, loaded the first time the gate mounts and kept while it stays mounted. */
+function useIndex(s) {
+    const [index, setIndex] = useState(null);
+    const { search, actions } = s;
+    useEffect(() => {
+        if (!search)
+            return;
+        let cancelled = false;
+        const got = search.docs ? Promise.resolve(search.docs) : search.load ? search.load() : Promise.resolve([]);
+        got
+            .then((m) => {
+            if (cancelled)
+                return;
+            const docs = Array.isArray(m) ? m : m.default;
+            setIndex(buildIndex([...actionDocs(actions, docs), ...docs]));
+        })
+            .catch(() => undefined);
+        return () => {
+            cancelled = true;
+        };
+    }, [search, actions]);
+    return index;
+}
+/** Everything a gate needs, for a gate built from scratch. `Gate.Root` calls it and shares it with the parts. */
+export function useGate({ open, onOpenChange }) {
+    const s = useSpotlight();
+    const { mode, actions, navigate } = s;
+    const copy = useMemo(() => mergeCopy(s.copy), [s.copy]);
+    const maxInput = s.ask?.maxInput ?? 1000;
+    const [query, setQuery] = useState("");
+    const index = useIndex(s);
+    const input = useRef(null);
+    const [focused, setFocused] = useState(false);
+    // Read on every opening: the panel writes the store as the conversation changes.
+    const [conversation, setConversation] = useState("none");
+    useEffect(() => {
+        if (!open)
+            return;
+        setConversation(s.ask ? conversationState(s.persist, s.ask.continueHours) : "none");
+        // A new opening starts empty, like Spotlight.
+        setQuery("");
+    }, [open]);
+    const typed = query.trim();
+    const askable = mode === "both" || mode === "ask";
+    const ask = (text) => {
+        const t = text.trim().slice(0, maxInput);
+        if (t && askable)
+            s.handOff({ kind: "ask", text: t, fresh: conversation === "stale" });
+    };
+    const runAction = (action, doc) => {
+        const value = action.fromSearch ? action.fromSearch(typed, doc) : undefined;
+        if (action.view && s.ask)
+            return s.handOff({ kind: "action", id: action.id, input: value });
+        onOpenChange(false);
+        action.run?.(value);
+    };
+    const onOpen = (doc) => {
+        if (doc.url) {
+            // A real click on the row's link, so a site's own link handling (a page transition
+            // listening to clicks) runs as for any other link.
+            const el = document.getElementById(searchApi.optionProps(searchApi.results.findIndex((r) => r.doc.id === doc.id)).id);
+            if (el instanceof HTMLAnchorElement)
+                el.click();
+            else {
+                onOpenChange(false);
+                navigate(doc.url, { from: "search" });
+            }
+            return;
+        }
+        const action = actionFor(doc, actions);
+        if (action)
+            runAction(action, doc);
+    };
+    const searchApi = useSearchAsk({
+        index,
+        query,
+        enabled: !!s.search,
+        onOpen,
+        ...(askable ? { onAsk: ask } : {}),
+        askRow: false,
+        ...(s.search?.limit ? { limit: s.search.limit } : {}),
+        kindOrder: s.search?.kindOrder ?? [],
+        ...(s.search?.snippetLength ? { snippetLength: s.search.snippetLength } : {}),
+    });
+    // What Enter does right now: ask, open the highlighted page, or the highlighted action's hint.
+    const active = searchApi.results[searchApi.active];
+    const activeAction = active ? actionFor(active.doc, actions) : undefined;
+    const hint = !active ? (askable ? copy.hintAsk : searchApi.count ? copy.hintOpen : null) : activeAction?.hint ?? copy.hintOpen;
+    /** Result links: modified clicks open a tab as usual; a click a site handler already took closes the gate; else navigate. */
+    const onLinkClick = (e) => {
+        if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey)
+            return;
+        if (e.defaultPrevented)
+            return onOpenChange(false);
+        e.preventDefault();
+        onOpenChange(false);
+        navigate(e.currentTarget.href, { from: "search" });
+    };
+    const placeholder = mode === "search" ? copy.placeholderSearch : mode === "ask" ? copy.placeholderAsk : copy.placeholder;
+    return {
+        spotlight: s,
+        mode,
+        open,
+        onOpenChange,
+        copy,
+        query,
+        setQuery,
+        typed,
+        index,
+        conversation,
+        focused,
+        inputRef: input,
+        search: searchApi,
+        ask,
+        askable,
+        onOpen,
+        onLinkClick,
+        /** What Enter does, for a hint by the field (`null`: nothing). */
+        hint,
+        /** The highlighted result's action, if it is one. */
+        activeAction,
+        actionFor: (doc) => actionFor(doc, actions),
+        kindLabel: (kind) => copy.kinds[kind] ?? kind,
+        /** Spread on the text field. */
+        inputProps: {
+            ref: input,
+            value: query,
+            onChange: (e) => setQuery(e.target.value),
+            onFocus: () => setFocused(true),
+            onBlur: () => setFocused(false),
+            ...searchApi.inputProps,
+            onKeyDown: (e) => {
+                if (searchApi.onKeyDown(e))
+                    return;
+                // Typed before the index arrived, or ask-only: Enter asks.
+                if (e.key === "Enter" && !e.nativeEvent.isComposing && typed && askable) {
+                    e.preventDefault();
+                    ask(query);
+                }
+            },
+            placeholder,
+            "aria-label": placeholder,
+            maxLength: maxInput,
+            enterKeyHint: askable ? "send" : "search",
+            autoComplete: "off",
+            autoCorrect: "off",
+            spellCheck: false,
+        },
+    };
+}
+const GateContext = createContext(null);
+/** The gate's state, inside `Gate.Root`. */
+export function useGateContext() {
+    const g = useContext(GateContext);
+    if (!g)
+        throw new Error("Gate parts must be inside <Gate.Root>");
+    return g;
+}
+/**
+ * The gate: a modal dialog (Radix) with an overlay, the focus moved into the field on open and
+ * back where it was on close, Escape clearing a highlighted row before it closes, and a press on
+ * the content box itself (the gaps between pieces) closing it like a press outside.
+ * State: `data-state` (open/closed), `data-mode`, `data-has-results` on the content.
+ */
+function Root({ open, onOpenChange, children, overlayProps, ...props }) {
+    const g = useGate({ open, onOpenChange });
+    return (_jsx(GateContext.Provider, { value: g, children: _jsx(Dialog.Root, { open: open, onOpenChange: onOpenChange, children: _jsxs(Dialog.Portal, { children: [_jsx(Dialog.Overlay, { "data-spotlight-overlay": "", ...overlayProps }), _jsxs(Dialog.Content, { "data-spotlight-gate": "", "data-mode": g.mode, "data-has-results": g.search.count > 0 || undefined, "aria-describedby": undefined, ...props, onPointerDown: (e) => {
+                            props.onPointerDown?.(e);
+                            if (e.target === e.currentTarget)
+                                onOpenChange(false);
+                        }, onOpenAutoFocus: (e) => {
+                            e.preventDefault();
+                            g.inputRef.current?.focus({ preventScroll: true });
+                        }, onCloseAutoFocus: (e) => {
+                            e.preventDefault();
+                            g.spotlight.restoreFocus();
+                        }, onEscapeKeyDown: (e) => {
+                            if (g.search.active === -1)
+                                return;
+                            e.preventDefault();
+                            g.search.setActive(-1);
+                        }, children: [_jsx(Dialog.Title, { style: srOnly, children: g.copy.gateTitle }), children, _jsx("p", { style: srOnly, role: "status", "aria-live": "polite", children: g.search.open ? g.copy.results(g.search.count) : "" })] })] }) }) }));
+}
+const srOnly = { position: "absolute", width: 1, height: 1, padding: 0, margin: -1, overflow: "hidden", clip: "rect(0,0,0,0)", whiteSpace: "nowrap", border: 0 };
+/** The text field. */
+function Input(props) {
+    const g = useGateContext();
+    return _jsx("input", { "data-spotlight-input": "", ...g.inputProps, ...props });
+}
+/** The listbox. Renders only while there are results; by default one `Gate.Item` per result. */
+function Results({ children, ...props }) {
+    const g = useGateContext();
+    if (!g.search.count)
+        return null;
+    return (_jsx("div", { "data-spotlight-results": "", ...g.search.listboxProps, "aria-label": g.copy.gateTitle, ...props, children: g.search.results.map((r, index) => (children ? _jsx(Fragment, { children: children({ ...r, index }) }, r.doc.id) : _jsx(Item, { result: r, index: index }, r.doc.id))) }));
+}
+/**
+ * One result: a link for a document with a `url`, a button for an action. State:
+ * `data-highlighted` (the arrow keys' row; also `aria-selected`), `data-kind`. Children default to
+ * the marked title and the snippet or subtitle.
+ */
+function Item({ result, index, children, ...props }) {
+    const g = useGateContext();
+    const option = g.search.optionProps(index);
+    const shared = {
+        ...option,
+        "data-spotlight-item": "",
+        "data-kind": result.doc.kind,
+        "data-highlighted": option["aria-selected"] || undefined,
+    };
+    const body = children ?? (_jsxs(_Fragment, { children: [_jsx("span", { "data-spotlight-title": "", children: _jsx(Marked, { text: result.doc.title, marks: result.titleMarks }) }), result.snippet ? (_jsx("span", { "data-spotlight-snippet": "", children: _jsx(Marked, { ...result.snippet }) })) : result.doc.subtitle ? (_jsx("span", { "data-spotlight-subtitle": "", children: result.doc.subtitle })) : null] }));
+    if (result.doc.url) {
+        return (_jsx("a", { href: result.doc.url, ...shared, ...props, onClick: (e) => {
+                props.onClick?.(e);
+                g.onLinkClick(e);
+            }, children: body }));
+    }
+    const { className, style } = props;
+    return (_jsx("button", { type: "button", ...shared, className: className, style: style, onClick: () => g.search.activate(index), children: body }));
+}
+/** Text with marked ranges in `<mark>` (style `mark[data-spotlight-mark]`). */
+export function Marked({ text, marks }) {
+    const parts = [];
+    let at = 0;
+    for (const [a, b] of marks) {
+        if (a > at)
+            parts.push(text.slice(at, a));
+        parts.push(_jsx("mark", { "data-spotlight-mark": "", children: text.slice(a, b) }, a));
+        at = b;
+    }
+    parts.push(text.slice(at));
+    return _jsx(_Fragment, { children: parts });
+}
+/** What Enter does, while it does something and the field has focus (`data-on`); children override the text. */
+function Hint({ children, ...props }) {
+    const g = useGateContext();
+    const on = g.focused && !!g.typed && !!g.hint;
+    return _jsx("span", { "data-spotlight-hint": "", "data-on": on || undefined, "aria-hidden": true, ...props, children: children ?? g.hint });
+}
+/** Closes the gate. */
+function Close(props) {
+    const g = useGateContext();
+    return _jsx(Dialog.Close, { "aria-label": g.copy.close, "data-spotlight-close": "", ...props });
+}
+/** Sends the typed text as a question (a send button for touch screens); only while there is text and Ask is on. */
+function Send(props) {
+    const g = useGateContext();
+    if (!g.typed || !g.askable)
+        return null;
+    return (_jsx("button", { type: "button", "aria-label": g.copy.send, "data-spotlight-send": "", ...props, onMouseDown: (e) => e.preventDefault(), onClick: () => g.ask(g.query) }));
+}
+export const Gate = { Root, Input, Results, Item, Hint, Close, Send, Marked };

package/dist/gate/useSearchAsk.d.ts

@@ -0,0 +1,90 @@
+import { type KeyboardEvent } from "react";
+import { type SearchDoc, type SearchIndex, type SearchResult } from "../core/search.js";
+export interface UseSearchAskOptions {
+    index: SearchIndex | null;
+    /** The field's current text. The host owns it (it is usually also the chat composer's value). */
+    query: string;
+    /** Off: no results, no key handling, plain field props (e.g. once a conversation has started). */
+    enabled?: boolean;
+    /** Open a result: navigate to `doc.url`, or run the host's own action for docs without one. */
+    onOpen: (doc: SearchDoc) => void;
+    /**
+     * Send the text as a question. With it, Enter asks unless a result is highlighted, and the
+     * last option is the ask row. Without it (plain site search), Enter opens the first result.
+     */
+    onAsk?: (query: string) => void;
+    /** With `onAsk`: list the ask row after the results (default). Off, Enter still asks; the host shows the hint itself. */
+    askRow?: boolean;
+    /**
+     * Rows listed after the results and the ask row, walked by the same arrow keys and opened with
+     * `onOpen` (e.g. a welcome list while nothing is typed or nothing matches). Shown on an empty
+     * query too. The host decides when to pass them.
+     */
+    extras?: SearchDoc[];
+    limit?: number;
+    kindOrder?: string[];
+    snippetLength?: number;
+}
+export interface SearchAskOption {
+    id: string;
+    role: "option";
+    "aria-selected": boolean;
+    /** Keeps the focus in the field when a row is clicked. */
+    onMouseDown: (e: {
+        preventDefault: () => void;
+    }) => void;
+}
+export declare function useSearchAsk({ index, query, enabled, onOpen, onAsk, extras, askRow, limit, kindOrder, snippetLength }: UseSearchAskOptions): {
+    /** Results in display order, and the same grouped by kind (each with its flat `index`). */
+    results: SearchResult[];
+    groups: {
+        kind: string;
+        results: {
+            index: number;
+            doc: SearchDoc;
+            score: number;
+            titleMarks: [start: number, end: number][];
+            snippet?: import("../core/search.js").Snippet;
+        }[];
+    }[];
+    /** True while text is typed and searched (results, maybe none, and the ask row). */
+    open: boolean;
+    /** True while the list has any row (results, the ask row or extras). */
+    listed: boolean;
+    /** The extras, each with its flat `index` (for `optionProps`). */
+    extras: {
+        doc: SearchDoc;
+        index: number;
+    }[];
+    /** The highlighted option, -1 for none. The ask row is `results.length`. */
+    active: number;
+    setActive: (i: number) => void;
+    onKeyDown: (e: KeyboardEvent<HTMLElement>) => boolean;
+    /** Open result `i` or, at `results.length`, ask. For row clicks. */
+    activate: (i: number) => void;
+    /** Number of results, for the host's live region ("3 results"). */
+    count: number;
+    /** Spread on the text field (combobox pattern; the focus never leaves it). Empty while disabled. */
+    inputProps: {
+        role: "combobox";
+        "aria-expanded": boolean;
+        "aria-controls": string | undefined;
+        "aria-autocomplete": "list";
+        "aria-activedescendant": string | undefined;
+    } | {
+        role?: undefined;
+        "aria-expanded"?: undefined;
+        "aria-controls"?: undefined;
+        "aria-autocomplete"?: undefined;
+        "aria-activedescendant"?: undefined;
+    };
+    /** Spread on the element that holds every option. */
+    listboxProps: {
+        id: string;
+        role: "listbox";
+    };
+    /** Spread on result row `i` (its flat index). */
+    optionProps: (i: number) => SearchAskOption;
+    /** Spread on the ask row; null without `onAsk`. */
+    askOptionProps: SearchAskOption | null;
+};