@perxel/spotlight 0.0.0-stage → 0.1.1

package/dist/gate/useSearchAsk.js

@@ -0,0 +1,122 @@
+"use client";
+// The search hook: search-as-you-type for one text field, with an optional "ask" on Enter.
+// No Next, no styling, no copy (the host renders the field, the rows and every label).
+// Imports only React and the core.
+import { useId, useMemo, useState } from "react";
+import { groupByKind, search } from "../core/search.js";
+const NO_EXTRAS = [];
+export function useSearchAsk({ index, query, enabled = true, onOpen, onAsk, extras = NO_EXTRAS, askRow = true, limit = 8, kindOrder = [], snippetLength }) {
+    const base = useId();
+    const listboxId = `${base}-results`;
+    // `on`: text typed and the index loaded, so there are results (maybe none) and an ask row.
+    const on = enabled && !!index && query.trim().length > 0;
+    const extraDocs = enabled ? extras : NO_EXTRAS;
+    const kindKey = kindOrder.join("\u0000");
+    const groups = useMemo(() => (on ? groupByKind(search(index, query, { limit, kindOrder, snippetLength }), kindOrder) : []), 
+    // `kindOrder` by value: callers often pass a new array literal each render.
+    [on, index, query, limit, kindKey, snippetLength]);
+    // Flat, in display order: what the arrow keys walk through.
+    const results = useMemo(() => groups.flatMap((g) => g.results), [groups]);
+    const askable = on && !!onAsk && askRow;
+    const askIndex = askable ? results.length : -1;
+    const extraStart = results.length + (askable ? 1 : 0);
+    const count = extraStart + extraDocs.length;
+    // The list shows when it has anything to show.
+    const listed = enabled && count > 0;
+    // The highlighted option, valid only for the query it was set on: typing clears it.
+    const [highlight, setHighlight] = useState({ query: "", i: -1 });
+    const active = listed && highlight.query === query && highlight.i < count ? highlight.i : -1;
+    const setActive = (i) => setHighlight({ query, i });
+    const optionId = (i) => `${base}-opt-${i}`;
+    const activate = (i) => {
+        if (i === askIndex)
+            onAsk(query.trim());
+        else if (i >= extraStart) {
+            if (extraDocs[i - extraStart])
+                onOpen(extraDocs[i - extraStart]);
+        }
+        else if (results[i])
+            onOpen(results[i].doc);
+    };
+    /** The field's key handler. Returns true when it handled the key (the host then does nothing). */
+    const onKeyDown = (e) => {
+        if (!enabled || e.nativeEvent.isComposing)
+            return false;
+        if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+            if (!count)
+                return false;
+            e.preventDefault();
+            const step = e.key === "ArrowDown" ? 1 : -1;
+            // From nothing, down goes to the first row and up to the last; both wrap through nothing.
+            const next = active === -1 ? (step > 0 ? 0 : count - 1) : active + step;
+            setActive(next < 0 || next >= count ? -1 : next);
+            return true;
+        }
+        if (e.key === "Escape" && active !== -1) {
+            // Clear the highlight only; a second Escape reaches the host (and closes its dialog).
+            e.preventDefault();
+            e.stopPropagation();
+            setActive(-1);
+            return true;
+        }
+        if (e.key === "Enter" && !e.shiftKey) {
+            if (active !== -1)
+                activate(active);
+            else if (!on)
+                return false;
+            else if (onAsk)
+                onAsk(query.trim());
+            else if (results[0])
+                onOpen(results[0].doc);
+            else
+                return false;
+            e.preventDefault();
+            return true;
+        }
+        return false;
+    };
+    const option = (i) => ({
+        id: optionId(i),
+        role: "option",
+        "aria-selected": i === active,
+        onMouseDown: (e) => e.preventDefault(),
+    });
+    return {
+        /** Results in display order, and the same grouped by kind (each with its flat `index`). */
+        results,
+        groups: useMemo(() => {
+            let i = 0;
+            return groups.map((g) => ({ kind: g.kind, results: g.results.map((r) => ({ ...r, index: i++ })) }));
+        }, [groups]),
+        /** True while text is typed and searched (results, maybe none, and the ask row). */
+        open: on,
+        /** True while the list has any row (results, the ask row or extras). */
+        listed,
+        /** The extras, each with its flat `index` (for `optionProps`). */
+        extras: useMemo(() => extraDocs.map((doc, i) => ({ doc, index: extraStart + i })), [extraDocs, extraStart]),
+        /** The highlighted option, -1 for none. The ask row is `results.length`. */
+        active,
+        setActive,
+        onKeyDown,
+        /** Open result `i` or, at `results.length`, ask. For row clicks. */
+        activate,
+        /** Number of results, for the host's live region ("3 results"). */
+        count: results.length,
+        /** Spread on the text field (combobox pattern; the focus never leaves it). Empty while disabled. */
+        inputProps: enabled && index
+            ? {
+                role: "combobox",
+                "aria-expanded": listed,
+                "aria-controls": listed ? listboxId : undefined,
+                "aria-autocomplete": "list",
+                "aria-activedescendant": active === -1 ? undefined : optionId(active),
+            }
+            : {},
+        /** Spread on the element that holds every option. */
+        listboxProps: { id: listboxId, role: "listbox" },
+        /** Spread on result row `i` (its flat index). */
+        optionProps: option,
+        /** Spread on the ask row; null without `onAsk`. */
+        askOptionProps: askable ? option(askIndex) : null,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { buildIndex, fold, groupByKind, markTerms, search } from "./core/search.js";
+export { conversationState, localStorageAdapter, noPersist, type ConversationState } from "./core/storage.js";
+export { calledTool, latestFromVisitor, sourcesOf, textOf, toolName, toolOutputOf } from "./core/messages.js";
+export { emailIn } from "./core/fold.js";
+export { defaultCopy, mergeCopy } from "./core/copy.js";
+export { defineAction } from "./types.js";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+// `@perxel/spotlight`: the core. No React, no AI SDK: the search engine, the conversation store
+// and message helpers, the contracts. Safe anywhere (browser, server, build scripts).
+export { buildIndex, fold, groupByKind, markTerms, search } from "./core/search.js";
+export { conversationState, localStorageAdapter, noPersist } from "./core/storage.js";
+export { calledTool, latestFromVisitor, sourcesOf, textOf, toolName, toolOutputOf } from "./core/messages.js";
+export { emailIn } from "./core/fold.js";
+export { defaultCopy, mergeCopy } from "./core/copy.js";
+export { defineAction } from "./types.js";

package/dist/liquid/context.d.ts

@@ -0,0 +1,26 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+import type { AskChat } from "../chat/useAskChat.js";
+/** The liquid skin's own options, read by its gate and panel (lazy chunks) from context. */
+export interface LiquidOptions {
+    /** The mark in the panel's header and next to "thinking" (an `<img>`, an SVG). */
+    logo?: ReactNode;
+    /** Heads every conversation: what happens to the questions. */
+    privacyNote?: ReactNode;
+    /** Under the conversation, when it returns something (e.g. contact options after a handoff tool call or an error). */
+    handoff?: (chat: AskChat) => ReactNode;
+    /** Left of the send button in the composer (e.g. a "send to us" link). */
+    composerExtra?: (chat: AskChat) => ReactNode;
+    /** Tools that only drive the interface: the answer text is not cut at them. */
+    uiTools?: string[];
+    /** Hosts whose links in answers and sources stay in the app (made relative, then `navigate`). The page's own host always does. */
+    localHosts?: string[];
+    /** The moving pools of accent colour behind the composer. */
+    tide?: boolean;
+    /** Extra attributes on the gate's and the panel's roots (`data-*` for a site's own scripts). */
+    gateProps?: HTMLAttributes<HTMLDivElement> & Record<`data-${string}`, string | boolean | undefined>;
+    panelProps?: HTMLAttributes<HTMLDivElement> & Record<`data-${string}`, string | boolean | undefined>;
+    /** Class on both roots (to set the theme variables on). */
+    className?: string;
+}
+export declare const LiquidContext: import("react").Context<LiquidOptions>;
+export declare function useLiquid(): LiquidOptions;

package/dist/liquid/context.js

@@ -0,0 +1,6 @@
+"use client";
+import { createContext, useContext } from "react";
+export const LiquidContext = createContext({});
+export function useLiquid() {
+    return useContext(LiquidContext);
+}

package/dist/liquid/gate.d.ts

@@ -0,0 +1,8 @@
+import "./liquid.css";
+import type { GateProps } from "../types.js";
+/**
+ * The liquid gate: like Spotlight, a glass box near the top over a dimmed, blurred page; under it,
+ * only when something matches, one glass group with every result. A hint in the box says what
+ * Enter does (keyboards), a send button replaces it on touch screens.
+ */
+export default function LiquidGate({ open, onOpenChange }: GateProps): import("react").JSX.Element;

package/dist/liquid/gate.js

@@ -0,0 +1,52 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useLayoutEffect, useState } from "react";
+import "./liquid.css";
+import { Gate, useGateContext } from "../gate/parts.js";
+import { useLiquid } from "./context.js";
+import { ArrowDownIcon, ArrowUpIcon, ArrowUpRightIcon, CornerDownLeftIcon, SearchIcon, XIcon } from "./icons.js";
+import { cx, PHONE_QUERY, REDUCED_MOTION, useMedia } from "./util.js";
+/** Phones: the gate's top in px, under the close button floating above the box; and its results' distance from the keyboard. */
+const PHONE_TOP = 64;
+const PHONE_BOTTOM = 16;
+/** Phones: the visible height (it shrinks when the keyboard opens), so the results end above the keyboard. */
+function useVisibleHeight(active) {
+    const [h, setH] = useState(null);
+    useEffect(() => {
+        const vv = window.visualViewport;
+        if (!active || !vv) {
+            setH(null);
+            return;
+        }
+        const update = () => setH(vv.height);
+        update();
+        vv.addEventListener("resize", update);
+        return () => vv.removeEventListener("resize", update);
+    }, [active]);
+    return h;
+}
+/**
+ * The liquid gate: like Spotlight, a glass box near the top over a dimmed, blurred page; under it,
+ * only when something matches, one glass group with every result. A hint in the box says what
+ * Enter does (keyboards), a send button replaces it on touch screens.
+ */
+export default function LiquidGate({ open, onOpenChange }) {
+    const liquid = useLiquid();
+    const phone = useMedia(PHONE_QUERY);
+    const visible = useVisibleHeight(open && phone);
+    const room = visible ? visible - PHONE_TOP - PHONE_BOTTOM : null;
+    return (_jsx(Gate.Root, { open: open, onOpenChange: onOpenChange, overlayProps: { className: cx("sp-overlay", liquid.className) }, ...liquid.gateProps, className: cx("sp-gate", liquid.className, liquid.gateProps?.className), style: room ? { maxHeight: room } : undefined, children: _jsx(Body, { phone: phone, room: room }) }));
+}
+function Body({ phone, room }) {
+    const g = useGateContext();
+    const { search } = g;
+    // The highlight is one glass piece that slides from row to row. Measured from the active row;
+    // coming from nothing it appears in place instead of sliding from the last row.
+    const [hl, setHl] = useState({ top: 0, height: 0, on: false, jump: true });
+    useLayoutEffect(() => {
+        const el = search.active === -1 ? null : document.getElementById(search.optionProps(search.active).id);
+        setHl((h) => (el ? { top: el.offsetTop, height: el.offsetHeight, on: true, jump: !h.on } : { ...h, on: false }));
+        el?.scrollIntoView({ block: "nearest", behavior: matchMedia(REDUCED_MOTION).matches ? "auto" : "smooth" });
+    }, [search.active, search.results]);
+    return (_jsxs(_Fragment, { children: [_jsx(Gate.Close, { className: "sp-liquid sp-glass sp-gate-close", children: _jsx(XIcon, {}) }), _jsxs("div", { className: "sp-liquid sp-glass sp-gate-box", children: [_jsx(SearchIcon, { className: "sp-gate-icon" }), _jsx(Gate.Input, { className: "sp-gate-input" }), phone ? (_jsx(Gate.Send, { className: "sp-fill sp-gate-send", children: _jsx(ArrowUpIcon, {}) })) : (_jsxs("span", { "aria-hidden": true, className: "sp-gate-hints", children: [_jsx("span", { "data-on": (g.focused && search.count > 0) || undefined, className: "sp-hint", children: _jsxs("kbd", { className: "sp-kbd sp-kbd-arrows", children: [_jsx(ArrowUpIcon, {}), _jsx(ArrowDownIcon, {})] }) }), _jsx("span", { "data-on": (g.focused && !!g.typed && !!g.hint) || undefined, className: "sp-hint", children: _jsxs("span", { className: "sp-hint-enter", children: [_jsx("kbd", { className: "sp-kbd", children: _jsx(CornerDownLeftIcon, {}) }), _jsx("span", { className: "sp-fade-in", children: g.hint }, g.hint ?? "")] }) })] }))] }), search.count > 0 && (_jsx("div", { className: "sp-liquid sp-glass sp-gate-results", children: _jsxs("div", { className: "sp-scroll", "data-lenis-prevent": "", style: room ? { maxHeight: room - 56 - 8 } : undefined, children: [_jsx(Gate.Results, { className: "sp-gate-list", children: ({ index, ...result }) => (_jsxs(Gate.Item, { result: result, index: index, className: "sp-row", style: { animationDelay: `${Math.min(index, 8) * 25}ms` }, children: [_jsxs("span", { className: "sp-row-text", children: [_jsx("span", { className: "sp-row-title", children: _jsx(Gate.Marked, { text: result.doc.title, marks: result.titleMarks }) }), result.snippet ? (_jsx("span", { className: "sp-row-sub sp-truncate", children: _jsx(Gate.Marked, { ...result.snippet }) })) : result.doc.subtitle ? (_jsx("span", { className: "sp-row-sub", children: result.doc.subtitle })) : null] }), _jsxs("span", { className: "sp-row-kind", children: [g.kindLabel(result.doc.kind), _jsx(ArrowUpRightIcon, { className: "sp-row-arrow" })] })] })) }), _jsx("span", { "aria-hidden": true, "data-on": hl.on || undefined, "data-jump": hl.jump || undefined, className: "sp-liquid sp-liquid-accent sp-hl", style: { transform: `translateY(${hl.top}px)`, height: hl.height } })] }) }))] }));
+}

package/dist/liquid/icons.d.ts

@@ -0,0 +1,12 @@
+import type { SVGProps } from "react";
+export declare const SearchIcon: (p: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const XIcon: (p: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const ArrowUpIcon: (p: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const ArrowDownIcon: (p: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const ArrowLeftIcon: (p: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const ArrowUpRightIcon: (p: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const CornerDownLeftIcon: (p: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const SquareIcon: (p: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const SquarePenIcon: (p: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const ChevronDownIcon: (p: SVGProps<SVGSVGElement>) => import("react").JSX.Element;
+export declare const FileTextIcon: (p: SVGProps<SVGSVGElement>) => import("react").JSX.Element;

package/dist/liquid/icons.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+function Icon({ children, ...props }) {
+    return (_jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": true, ...props, children: children }));
+}
+export const SearchIcon = (p) => _jsxs(Icon, { ...p, children: [_jsx("circle", { cx: "11", cy: "11", r: "8" }), _jsx("path", { d: "m21 21-4.3-4.3" })] });
+export const XIcon = (p) => _jsxs(Icon, { ...p, children: [_jsx("path", { d: "M18 6 6 18" }), _jsx("path", { d: "m6 6 12 12" })] });
+export const ArrowUpIcon = (p) => _jsxs(Icon, { ...p, children: [_jsx("path", { d: "m5 12 7-7 7 7" }), _jsx("path", { d: "M12 19V5" })] });
+export const ArrowDownIcon = (p) => _jsxs(Icon, { ...p, children: [_jsx("path", { d: "M12 5v14" }), _jsx("path", { d: "m19 12-7 7-7-7" })] });
+export const ArrowLeftIcon = (p) => _jsxs(Icon, { ...p, children: [_jsx("path", { d: "m12 19-7-7 7-7" }), _jsx("path", { d: "M19 12H5" })] });
+export const ArrowUpRightIcon = (p) => _jsxs(Icon, { ...p, children: [_jsx("path", { d: "M7 7h10v10" }), _jsx("path", { d: "M7 17 17 7" })] });
+export const CornerDownLeftIcon = (p) => _jsxs(Icon, { ...p, children: [_jsx("path", { d: "M20 4v7a4 4 0 0 1-4 4H4" }), _jsx("path", { d: "m9 10-5 5 5 5" })] });
+export const SquareIcon = (p) => _jsx(Icon, { ...p, children: _jsx("rect", { width: "18", height: "18", x: "3", y: "3", rx: "2" }) });
+export const SquarePenIcon = (p) => (_jsxs(Icon, { ...p, children: [_jsx("path", { d: "M12 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7" }), _jsx("path", { d: "M18.375 2.625a1 1 0 0 1 3 3l-9.013 9.014a2 2 0 0 1-.853.505l-2.873.84a.5.5 0 0 1-.62-.62l.84-2.873a2 2 0 0 1 .506-.852z" })] }));
+export const ChevronDownIcon = (p) => _jsx(Icon, { ...p, children: _jsx("path", { d: "m6 9 6 6 6-6" }) });
+export const FileTextIcon = (p) => (_jsxs(Icon, { ...p, children: [_jsx("path", { d: "M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z" }), _jsx("path", { d: "M14 2v4a2 2 0 0 0 2 2h4" }), _jsx("path", { d: "M10 9H8" }), _jsx("path", { d: "M16 13H8" }), _jsx("path", { d: "M16 17H8" })] }));

package/dist/liquid/index.d.ts

@@ -0,0 +1,9 @@
+import type { SpotlightProps } from "../types.js";
+import { type LiquidOptions } from "./context.js";
+export type SpotlightLiquidProps = Omit<SpotlightProps, "gate" | "panel"> & LiquidOptions;
+/** The provider with the liquid gate and panel. Wrap the app (or the part that offers search/ask). */
+export declare function SpotlightLiquid({ logo, privacyNote, handoff, composerExtra, uiTools, localHosts, tide, gateProps, panelProps, className, ...props }: SpotlightLiquidProps): import("react").JSX.Element;
+export type { LiquidOptions };
+export { Trigger, useSpotlight, isMac, shortcutLabel } from "../react/provider.js";
+export { localStorageAdapter } from "../core/storage.js";
+export { turnstileWidget } from "../react/turnstile.js";

package/dist/liquid/index.js

@@ -0,0 +1,19 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+// `@perxel/spotlight/liquid`: the default skin. Glass gate and panel, themed with CSS variables.
+// The gate and the panel are lazy chunks that import the skin's CSS themselves, so a page's first
+// load holds only the provider and the triggers, and no stylesheet. (`@perxel/spotlight/liquid.css`
+// is also exported, for a bundler that does not load CSS imported from a package.)
+import { SpotlightProvider } from "../react/provider.js";
+import { LiquidContext } from "./context.js";
+const gate = () => import("./gate.js");
+const panel = () => import("./panel.js");
+/** The provider with the liquid gate and panel. Wrap the app (or the part that offers search/ask). */
+export function SpotlightLiquid({ logo, privacyNote, handoff, composerExtra, uiTools, localHosts, tide, gateProps, panelProps, className, ...props }) {
+    const options = { logo, privacyNote, handoff, composerExtra, uiTools, localHosts, tide, gateProps, panelProps, className };
+    return (_jsx(LiquidContext.Provider, { value: options, children: _jsx(SpotlightProvider, { ...props, gate: gate, panel: panel }) }));
+}
+// The light parts of `./react`, so a site on the skin imports from one place.
+export { Trigger, useSpotlight, isMac, shortcutLabel } from "../react/provider.js";
+export { localStorageAdapter } from "../core/storage.js";
+export { turnstileWidget } from "../react/turnstile.js";