@livo-build/kit 0.1.0 → 0.1.6

package/README.md

@@ -102,16 +102,56 @@ const { data } = useSubgraph({ url, query: GET_ITEMS });  // your indexer's grap
 <Card/>  <Skeleton width={120}/>  <Spinner/>  <EmptyState title="Nothing yet"/>  <CopyButton value={addr}/>
 ```
 
+## Theme it from one object
+
+```tsx
+<KitThemeProvider theme={{ accent: "#6d28d9", radius: 16 }}>
+  {/* every kit component beneath inherits the brand */}
+</KitThemeProvider>
+```
+
+## Accounts, tokens, approvals
+
+```tsx
+<RequireConnection>{/* shown only when connected; else a connect prompt */}</RequireConnection>
+<Connected><Identity address={addr} /></Connected>   <Avatar address={addr} />
+
+const { symbol, decimals } = useToken(token);
+const { enough } = useAllowance({ token, owner, spender });
+<ApproveButton token={token} spender={spender} amount={amt} />   // approve → toast → done
+```
+
+## Link a wallet to Telegram
+
+For apps that have both a Telegram bot and a web instance — verify the same person on both.
+
+```tsx
+<LinkTelegramButton />                    // Mini App: uses verified initData; web: bot deep-link
+const { status, telegram, link } = useTelegramLink();   // headless
+const mini = useTelegramMiniApp();        // { available, initData, user } when open inside Telegram
+```
+
+The hook talks to your `api/` (same-origin), which verifies both proofs with
+`@livo-build/runtime` (`verifyTelegramInitData` + a signed-nonce check) and writes
+the binding to D1 (`TelegramLinks`). Endpoints it expects under `endpoint` (default
+`/api/telegram`): `GET /nonce`, `GET /status`, `POST /link` (Mini App), `POST /start`
+(web deep-link), `POST /unlink`. (Livo's `telegram-app` blueprint scaffolds these.)
+
 ## Exports
 
 - **wallet** — `ConnectWallet`, `WalletModal`, `useWalletConnectors`
+- **telegram** — `LinkTelegramButton`, `useTelegramLink`, `useTelegramMiniApp`
 - **provider** — `LivoWeb3Provider`
-- **contracts** — `createLivoContracts`, `useContractValue`, `resolveAddress`
+- **contracts** — `createLivoContracts`, `useContractValue`, `useContractEvent`, `resolveAddress`
 - **tx** — `TxButton`, `useTx`, `decodeRevert`
 - **toast** — `ToastProvider`, `useToast`
-- **data** — `useApi`, `apiClient`, `useSubgraph`
-- **web3** — `Address`, `Balance`, `NetworkGuard`, `TokenAmountInput`
-- **ui** — `Dialog`, `Card`, `Skeleton`, `Spinner`, `EmptyState`, `CopyButton`
+- **data** — `useApi`, `apiClient`, `useSubgraph`, `Async`
+- **token** — `useToken`, `useAllowance`, `useApprove`, `ApproveButton`
+- **account** — `Connected`, `Disconnected`, `RequireConnection`, `useIsConnected`, `Avatar`, `Identity`
+- **web3** — `Address`, `Balance`, `NetworkGuard`, `TokenAmountInput`, `ChainSwitcher`, `AddressInput`
+- **ui** — `Dialog`, `Card`, `Skeleton`, `Spinner`, `EmptyState`, `CopyButton`, `Button`, `Badge`
+- **theme** — `KitThemeProvider`
+- **hooks** — `useCopyToClipboard`, `useLocalStorage`, `useDebounce`, `useInterval`
 - **format** — `shortAddress`, `shortHash`, `formatToken`, `parseToken`, `formatUsd`, `timeAgo`, `avatarGradient`
 
 Every component is neutral by default — **style it** (see [STYLING.md](./STYLING.md)).

package/dist/account/Avatar.d.ts

@@ -0,0 +1,9 @@
+import "./account.css";
+export interface AvatarProps {
+    address: `0x${string}`;
+    size?: number;
+    /** Resolve + use the ENS avatar when available. Default true. */
+    ens?: boolean;
+    className?: string;
+}
+export declare function Avatar({ address, size, ens, className }: AvatarProps): import("react").JSX.Element;

package/dist/account/Avatar.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import "./account.css";
+import { useEnsName, useEnsAvatar } from "wagmi";
+import { avatarGradient } from "../format";
+import { cx } from "../util";
+// An account avatar: the ENS avatar when set, otherwise a deterministic gradient
+// identicon derived from the address (no image dependency). Neutral.
+export function Avatar({ address, size = 32, ens = true, className }) {
+    const { data: name } = useEnsName({ address, query: { enabled: ens } });
+    const { data: url } = useEnsAvatar({ name: name ?? undefined, query: { enabled: ens && Boolean(name) } });
+    if (url) {
+        return _jsx("img", { className: cx("kit-avatar", className), src: url, width: size, height: size, alt: "", style: { borderRadius: "50%" } });
+    }
+    return (_jsx("span", { className: cx("kit-avatar", className), style: { width: size, height: size, borderRadius: "50%", background: avatarGradient(address), display: "inline-block" }, "aria-hidden": "true" }));
+}

package/dist/account/Identity.d.ts

@@ -0,0 +1,9 @@
+import "./account.css";
+export interface IdentityProps {
+    address: `0x${string}`;
+    size?: number;
+    /** Resolve ENS name/avatar. Default true. */
+    ens?: boolean;
+    className?: string;
+}
+export declare function Identity({ address, size, ens, className }: IdentityProps): import("react").JSX.Element;

package/dist/account/Identity.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import "./account.css";
+import { useEnsName } from "wagmi";
+import { Avatar } from "./Avatar";
+import { shortAddress } from "../format";
+import { cx } from "../util";
+// Avatar + name (ENS or shortened address) in a row. Neutral; style .kit-identity.
+export function Identity({ address, size = 28, ens = true, className }) {
+    const { data: name } = useEnsName({ address, query: { enabled: ens } });
+    return (_jsxs("span", { className: cx("kit-identity", className), children: [_jsx(Avatar, { address: address, size: size, ens: ens }), _jsx("span", { className: "kit-identity-name", children: name || shortAddress(address) })] }));
+}

package/dist/account/account.css

@@ -0,0 +1,3 @@
+.kit-avatar{flex:none;object-fit:cover}
+.kit-identity{display:inline-flex;align-items:center;gap:8px;font:inherit;font-weight:500}
+.kit-identity-name{font-variant-numeric:tabular-nums}

package/dist/account/gates.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from "react";
+/** Whether a wallet is currently connected. */
+export declare function useIsConnected(): boolean;
+/** Render children only when a wallet is connected (else `fallback`). */
+export declare function Connected({ children, fallback }: {
+    children: ReactNode;
+    fallback?: ReactNode;
+}): import("react").JSX.Element;
+/** Render children only when NO wallet is connected. */
+export declare function Disconnected({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element | null;
+/** Gate UI behind a connection: shows the children when connected, otherwise a
+ *  connect prompt (the kit's <ConnectWallet/> by default — pass `connect` to override). */
+export declare function RequireConnection({ children, connect }: {
+    children: ReactNode;
+    connect?: ReactNode;
+}): import("react").JSX.Element;

package/dist/account/gates.js

@@ -0,0 +1,21 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import {} from "react";
+import { useConnection } from "wagmi";
+import { ConnectWallet } from "../wallet";
+/** Whether a wallet is currently connected. */
+export function useIsConnected() {
+    return useConnection().isConnected;
+}
+/** Render children only when a wallet is connected (else `fallback`). */
+export function Connected({ children, fallback }) {
+    return useIsConnected() ? _jsx(_Fragment, { children: children }) : _jsx(_Fragment, { children: fallback ?? null });
+}
+/** Render children only when NO wallet is connected. */
+export function Disconnected({ children }) {
+    return useIsConnected() ? null : _jsx(_Fragment, { children: children });
+}
+/** Gate UI behind a connection: shows the children when connected, otherwise a
+ *  connect prompt (the kit's <ConnectWallet/> by default — pass `connect` to override). */
+export function RequireConnection({ children, connect }) {
+    return useIsConnected() ? _jsx(_Fragment, { children: children }) : _jsx(_Fragment, { children: connect ?? _jsx(ConnectWallet, {}) });
+}

package/dist/account/index.d.ts

@@ -0,0 +1,3 @@
+export { useIsConnected, Connected, Disconnected, RequireConnection } from "./gates";
+export { Avatar, type AvatarProps } from "./Avatar";
+export { Identity, type IdentityProps } from "./Identity";

package/dist/account/index.js

@@ -0,0 +1,3 @@
+export { useIsConnected, Connected, Disconnected, RequireConnection } from "./gates";
+export { Avatar } from "./Avatar";
+export { Identity } from "./Identity";

package/dist/auth/SignInWithEthereum.d.ts

@@ -0,0 +1,8 @@
+import "../wallet/wallet.css";
+import { type ReactNode } from "react";
+import { useSiwe, type UseSiweOptions } from "./useSiwe";
+export interface SignInWithEthereumProps extends UseSiweOptions {
+    className?: string;
+    children?: (api: ReturnType<typeof useSiwe>) => ReactNode;
+}
+export declare function SignInWithEthereum({ className, children, ...opts }: SignInWithEthereumProps): import("react").JSX.Element;

package/dist/auth/SignInWithEthereum.js

@@ -0,0 +1,18 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import "../wallet/wallet.css";
+import {} from "react";
+import { useSiwe } from "./useSiwe";
+import { shortAddress } from "../format";
+import { cx } from "../util";
+// A button that runs the Sign-In With Ethereum flow and reflects session state.
+// Pass `children` for a custom render. Reuses the wallet-connect button styling.
+export function SignInWithEthereum({ className, children, ...opts }) {
+    const siwe = useSiwe(opts);
+    if (children)
+        return _jsx(_Fragment, { children: children(siwe) });
+    if (siwe.status === "signed-in") {
+        return (_jsxs("button", { className: cx("wm-account", className), onClick: () => siwe.signOut(), children: [shortAddress(siwe.user?.address), " \u00B7 Sign out"] }));
+    }
+    const busy = siwe.status === "signing" || siwe.status === "loading";
+    return (_jsx("button", { className: cx("wm-cta", className), disabled: busy, onClick: () => siwe.signIn(), children: siwe.status === "signing" ? "Check your wallet…" : "Sign in with Ethereum" }));
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,2 @@
+export { useSiwe, type SiweState, type SiweStatus, type SiweUser, type UseSiweOptions } from "./useSiwe";
+export { SignInWithEthereum, type SignInWithEthereumProps } from "./SignInWithEthereum";

package/dist/auth/index.js

@@ -0,0 +1,2 @@
+export { useSiwe } from "./useSiwe";
+export { SignInWithEthereum } from "./SignInWithEthereum";

package/dist/auth/useSiwe.d.ts

@@ -0,0 +1,18 @@
+export type SiweStatus = "loading" | "signed-out" | "signing" | "signed-in" | "error";
+export interface SiweUser {
+    address: string;
+    [key: string]: unknown;
+}
+export interface SiweState {
+    status: SiweStatus;
+    user?: SiweUser;
+    signIn: () => Promise<void>;
+    signOut: () => Promise<void>;
+    refresh: () => void;
+    error?: Error;
+}
+export interface UseSiweOptions {
+    /** Base path of the SIWE auth API (default "/api/auth"). */
+    endpoint?: string;
+}
+export declare function useSiwe(options?: UseSiweOptions): SiweState;

package/dist/auth/useSiwe.js

@@ -0,0 +1,72 @@
+import { useCallback, useEffect, useState } from "react";
+import { useConnection, useSignMessage } from "wagmi";
+// Sign-In With Ethereum against a same-origin backend. Expects: GET {endpoint}/nonce
+// → { nonce, message }, POST {endpoint}/verify { message, signature } → { user },
+// GET {endpoint}/me → { user } | 401, POST {endpoint}/logout. The server builds the
+// SIWE message (with createSiweMessage from @livo-build/runtime) and the session.
+export function useSiwe(options = {}) {
+    const base = options.endpoint ?? "/api/auth";
+    const { address } = useConnection();
+    const { signMessageAsync } = useSignMessage();
+    const [status, setStatus] = useState("loading");
+    const [user, setUser] = useState();
+    const [error, setError] = useState();
+    const refresh = useCallback(async () => {
+        try {
+            const r = await fetch(`${base}/me`, { credentials: "include" });
+            if (r.ok) {
+                const j = (await r.json());
+                if (j.user) {
+                    setUser(j.user);
+                    setStatus("signed-in");
+                    return;
+                }
+            }
+            setStatus("signed-out");
+        }
+        catch (e) {
+            setError(e);
+            setStatus("error");
+        }
+    }, [base]);
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    const signIn = useCallback(async () => {
+        if (!address)
+            return;
+        setStatus("signing");
+        setError(undefined);
+        try {
+            const nr = await fetch(`${base}/nonce?address=${address}`, { credentials: "include" });
+            const { message } = (await nr.json());
+            const signature = await signMessageAsync({ message });
+            const vr = await fetch(`${base}/verify`, {
+                method: "POST",
+                credentials: "include",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ message, signature }),
+            });
+            const j = (await vr.json());
+            if (!vr.ok || !j.user)
+                throw new Error(j.error ?? "Sign-in failed");
+            setUser(j.user);
+            setStatus("signed-in");
+        }
+        catch (e) {
+            setError(e);
+            setStatus("error");
+        }
+    }, [address, base, signMessageAsync]);
+    const signOut = useCallback(async () => {
+        try {
+            await fetch(`${base}/logout`, { method: "POST", credentials: "include" });
+        }
+        catch {
+            /* ignore */
+        }
+        setUser(undefined);
+        setStatus("signed-out");
+    }, [base]);
+    return { status, user, signIn, signOut, refresh: () => void refresh(), error };
+}

package/dist/contracts/index.d.ts

@@ -1,2 +1,3 @@
 export { useContractValue, type UseContractValueParams } from "./useContractValue";
+export { useContractEvent, type UseContractEventParams } from "./useContractEvent";
 export { createLivoContracts, resolveAddress, type LivoBindings, type LivoContracts, type ContractRef, } from "./createLivoContracts";

package/dist/contracts/index.js

@@ -1,2 +1,3 @@
 export { useContractValue } from "./useContractValue";
+export { useContractEvent } from "./useContractEvent";
 export { createLivoContracts, resolveAddress, } from "./createLivoContracts";

package/dist/contracts/useContractEvent.d.ts

@@ -0,0 +1,10 @@
+import type { Abi } from "viem";
+export interface UseContractEventParams {
+    address?: `0x${string}`;
+    abi: Abi;
+    eventName: string;
+    onLogs: (logs: readonly unknown[]) => void;
+    chainId?: number;
+    enabled?: boolean;
+}
+export declare function useContractEvent({ address, abi, eventName, onLogs, chainId, enabled }: UseContractEventParams): void;

package/dist/contracts/useContractEvent.js

@@ -0,0 +1,13 @@
+import { useWatchContractEvent } from "wagmi";
+// Subscribe to a contract event (live). A thin wrapper over useWatchContractEvent —
+// pair with createLivoContracts' useContract(name) to get { address, abi }.
+export function useContractEvent({ address, abi, eventName, onLogs, chainId, enabled }) {
+    useWatchContractEvent({
+        address,
+        abi,
+        eventName,
+        chainId,
+        enabled: (enabled ?? true) && Boolean(address),
+        onLogs: (logs) => onLogs(logs),
+    });
+}

package/dist/data/Async.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from "react";
+export interface AsyncQuery<T> {
+    data: T | undefined;
+    error: Error | null;
+    isLoading: boolean;
+}
+export interface AsyncProps<T> {
+    query: AsyncQuery<T>;
+    /** Render the loaded data. */
+    children: (data: T) => ReactNode;
+    loading?: ReactNode;
+    error?: (error: Error) => ReactNode;
+    /** Shown when data is "empty" (default: [] or null/undefined). */
+    empty?: ReactNode;
+    isEmpty?: (data: T) => boolean;
+}
+export declare function Async<T>({ query, children, loading, error, empty, isEmpty }: AsyncProps<T>): import("react").JSX.Element;

package/dist/data/Async.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import {} from "react";
+import { Spinner } from "../ui";
+// Render the loading / error / empty / data states of ANY kit data hook in one
+// place — `<Async query={useApi("/items")}>{(items) => …}</Async>`. Neutral
+// defaults (spinner, plain error); pass your own for each state.
+export function Async({ query, children, loading, error, empty, isEmpty }) {
+    if (query.error) {
+        return _jsx(_Fragment, { children: error ? error(query.error) : _jsx("span", { className: "kit-async-error", children: query.error.message }) });
+    }
+    if (query.isLoading || query.data === undefined) {
+        return _jsx(_Fragment, { children: loading ?? _jsx(Spinner, {}) });
+    }
+    const emptyVal = isEmpty
+        ? isEmpty(query.data)
+        : Array.isArray(query.data)
+            ? query.data.length === 0
+            : query.data === null;
+    if (emptyVal && empty !== undefined)
+        return _jsx(_Fragment, { children: empty });
+    return _jsx(_Fragment, { children: children(query.data) });
+}

package/dist/data/DataTable.d.ts

@@ -0,0 +1,26 @@
+import "./data.css";
+import { type ReactNode } from "react";
+export interface Column<T> {
+    /** Field key (also the default sort key) or a synthetic id. */
+    key: keyof T | string;
+    header: ReactNode;
+    /** Custom cell render; defaults to String(item[key]). */
+    render?: (item: T, index: number) => ReactNode;
+    /** Allow clicking the header to sort by this column's key. Default false. */
+    sortable?: boolean;
+    align?: "left" | "right" | "center";
+    className?: string;
+}
+export interface DataTableProps<T> {
+    data: T[];
+    columns: Column<T>[];
+    pageSize?: number;
+    searchable?: boolean;
+    searchKeys?: (keyof T)[];
+    searchPlaceholder?: string;
+    empty?: ReactNode;
+    rowKey?: (item: T, index: number) => string | number;
+    onRowClick?: (item: T) => void;
+    className?: string;
+}
+export declare function DataTable<T>({ data, columns, pageSize, searchable, searchKeys, searchPlaceholder, empty, rowKey, onRowClick, className, }: DataTableProps<T>): import("react").JSX.Element;

package/dist/data/DataTable.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import "./data.css";
+import {} from "react";
+import { useCollection } from "./useCollection";
+import { cx } from "../util";
+// A neutral, sortable, searchable, paginated table over an array (data wrangling
+// done for you via useCollection). Style via .kit-table* — see STYLING.md.
+export function DataTable({ data, columns, pageSize, searchable, searchKeys, searchPlaceholder = "Search…", empty, rowKey, onRowClick, className, }) {
+    const cfg = { pageSize, searchKeys };
+    const c = useCollection(data, cfg);
+    return (_jsxs("div", { className: cx("kit-table-wrap", className), children: [searchable && (_jsx("input", { className: "kit-table-search", value: c.query, placeholder: searchPlaceholder, onChange: (e) => c.setQuery(e.target.value) })), _jsxs("table", { className: "kit-table", children: [_jsx("thead", { children: _jsx("tr", { children: columns.map((col) => {
+                                const active = c.sort?.key === col.key;
+                                return (_jsxs("th", { "data-align": col.align, "data-sortable": col.sortable || undefined, "data-active": active || undefined, className: col.className, onClick: col.sortable ? () => c.toggleSort(col.key) : undefined, children: [col.header, active ? _jsx("span", { className: "kit-table-caret", children: c.sort?.dir === "asc" ? " ▲" : " ▼" }) : null] }, String(col.key)));
+                            }) }) }), _jsx("tbody", { children: c.isEmpty ? (_jsx("tr", { className: "kit-table-empty", children: _jsx("td", { colSpan: columns.length, children: empty ?? "No results" }) })) : (c.items.map((item, i) => (_jsx("tr", { "data-clickable": onRowClick ? true : undefined, onClick: onRowClick ? () => onRowClick(item) : undefined, children: columns.map((col) => (_jsx("td", { "data-align": col.align, className: col.className, children: col.render ? col.render(item, i) : String(item[col.key] ?? "") }, String(col.key)))) }, rowKey ? rowKey(item, i) : i)))) })] }), pageSize && c.pageCount > 1 && (_jsxs("div", { className: "kit-table-pager", children: [_jsx("button", { className: "kit-table-page-btn", disabled: c.page === 0, onClick: c.prevPage, children: "\u2039 Prev" }), _jsxs("span", { className: "kit-table-page-info", children: [c.page + 1, " / ", c.pageCount] }), _jsx("button", { className: "kit-table-page-btn", disabled: c.page >= c.pageCount - 1, onClick: c.nextPage, children: "Next \u203A" })] }))] }));
+}

package/dist/data/data.css

@@ -0,0 +1,22 @@
+/* DataTable — neutral, restyle via .kit-table* or --kit-* vars. */
+.kit-table-wrap{display:flex;flex-direction:column;gap:10px;font:inherit}
+.kit-table-search{align-self:flex-start;min-width:220px;border:1px solid var(--kit-border,#e5e7eb);border-radius:10px;padding:8px 12px;font:inherit;font-size:14px;background:transparent;color:inherit}
+.kit-table-search:focus{outline:0;border-color:var(--kit-muted,#6b7280)}
+.kit-table{width:100%;border-collapse:collapse;font-size:14px}
+.kit-table th,.kit-table td{padding:10px 12px;text-align:left;border-bottom:1px solid var(--kit-border,#eceef1)}
+.kit-table td[data-align="right"],.kit-table th[data-align="right"]{text-align:right;font-variant-numeric:tabular-nums}
+.kit-table td[data-align="center"],.kit-table th[data-align="center"]{text-align:center}
+.kit-table th{font-weight:600;color:var(--kit-muted,#6b7280);user-select:none;white-space:nowrap}
+.kit-table th[data-sortable]{cursor:pointer}
+.kit-table th[data-active]{color:var(--kit-fg,#111827)}
+.kit-table-caret{font-size:10px}
+.kit-table tbody tr[data-clickable]{cursor:pointer}
+.kit-table tbody tr[data-clickable]:hover{background:var(--kit-row-hover,#f6f7f9)}
+.kit-table-empty td{padding:28px 12px;text-align:center;color:var(--kit-muted,#6b7280)}
+.kit-table-pager{display:flex;align-items:center;gap:12px}
+.kit-table-page-btn{border:1px solid var(--kit-border,#e5e7eb);background:transparent;color:inherit;border-radius:9px;padding:6px 12px;font:inherit;font-size:13px;cursor:pointer}
+.kit-table-page-btn:disabled{opacity:.45;cursor:default}
+.kit-table-page-info{color:var(--kit-muted,#6b7280);font-size:13px;font-variant-numeric:tabular-nums}
+@media (prefers-color-scheme:dark){
+  .kit-table-wrap{--kit-border:#2c2e36;--kit-fg:#f5f5f7;--kit-row-hover:#1d1f25}
+}

package/dist/data/index.d.ts

@@ -1,2 +1,7 @@
 export { useApi, apiClient, type QueryResult, type UseApiOptions } from "./useApi";
 export { useSubgraph, type UseSubgraphArgs } from "./useSubgraph";
+export { Async, type AsyncProps, type AsyncQuery } from "./Async";
+export { useCollection, processCollection, type Collection, type CollectionConfig, type SortState, type SortDir, } from "./useCollection";
+export { DataTable, type DataTableProps, type Column } from "./DataTable";
+export { useEventSource, type EventSourceState, type UseEventSourceOptions, type StreamStatus } from "./useEventSource";
+export { useWebSocket, type WebSocketState, type UseWebSocketOptions } from "./useWebSocket";

package/dist/data/index.js

@@ -1,2 +1,7 @@
 export { useApi, apiClient } from "./useApi";
 export { useSubgraph } from "./useSubgraph";
+export { Async } from "./Async";
+export { useCollection, processCollection, } from "./useCollection";
+export { DataTable } from "./DataTable";
+export { useEventSource } from "./useEventSource";
+export { useWebSocket } from "./useWebSocket";

package/dist/data/useCollection.d.ts

@@ -0,0 +1,42 @@
+export type SortDir = "asc" | "desc";
+export interface SortState<T> {
+    key: keyof T;
+    dir: SortDir;
+}
+export interface CollectionConfig<T> {
+    /** Keys to full-text search (case-insensitive). Default: all string/number fields. */
+    searchKeys?: (keyof T)[];
+    /** Custom search predicate (overrides searchKeys). */
+    search?: (item: T, query: string) => boolean;
+    /** Persistent filter applied before search/sort. */
+    filter?: (item: T) => boolean;
+    /** Rows per page. Omit/0 to disable paging (one page). */
+    pageSize?: number;
+    initialSort?: SortState<T>;
+    initialQuery?: string;
+}
+export declare function processCollection<T>(items: T[], state: {
+    query?: string;
+    sort?: SortState<T> | null;
+} & Pick<CollectionConfig<T>, "searchKeys" | "search" | "filter">): T[];
+export interface Collection<T> {
+    /** The current page of processed rows. */
+    items: T[];
+    /** All processed (filtered+searched+sorted) rows, across pages. */
+    all: T[];
+    query: string;
+    setQuery: (q: string) => void;
+    sort: SortState<T> | null;
+    /** Set/toggle the sort key (same key flips asc↔desc). */
+    toggleSort: (key: keyof T) => void;
+    setSort: (sort: SortState<T> | null) => void;
+    page: number;
+    setPage: (p: number) => void;
+    nextPage: () => void;
+    prevPage: () => void;
+    pageCount: number;
+    /** Count after filter+search (before paging). */
+    total: number;
+    isEmpty: boolean;
+}
+export declare function useCollection<T>(items: T[], config?: CollectionConfig<T>): Collection<T>;

package/dist/data/useCollection.js

@@ -0,0 +1,67 @@
+import { useMemo, useState } from "react";
+function compare(a, b) {
+    if (a == null)
+        return b == null ? 0 : -1;
+    if (b == null)
+        return 1;
+    if (typeof a === "number" && typeof b === "number")
+        return a - b;
+    if (typeof a === "bigint" && typeof b === "bigint")
+        return a < b ? -1 : a > b ? 1 : 0;
+    return String(a).localeCompare(String(b), undefined, { numeric: true });
+}
+// Pure: filter → search → sort. Exported for testing and non-React use.
+export function processCollection(items, state) {
+    let out = state.filter ? items.filter(state.filter) : items.slice();
+    const q = (state.query ?? "").trim().toLowerCase();
+    if (q) {
+        out = out.filter((item) => {
+            if (state.search)
+                return state.search(item, q);
+            const keys = state.searchKeys ?? Object.keys(item);
+            return keys.some((k) => {
+                const v = item[k];
+                return (typeof v === "string" || typeof v === "number") && String(v).toLowerCase().includes(q);
+            });
+        });
+    }
+    if (state.sort) {
+        const { key, dir } = state.sort;
+        const f = dir === "asc" ? 1 : -1;
+        out.sort((a, b) => compare(a[key], b[key]) * f);
+    }
+    return out;
+}
+// Headless client-side data wrangling: search + sort + paginate any array, with
+// React state. Feed `items` (e.g. from useApi/useSubgraph) and render `items`.
+export function useCollection(items, config = {}) {
+    const [query, setQueryRaw] = useState(config.initialQuery ?? "");
+    const [sort, setSort] = useState(config.initialSort ?? null);
+    const [page, setPage] = useState(0);
+    const setQuery = (q) => {
+        setQueryRaw(q);
+        setPage(0);
+    };
+    const toggleSort = (key) => setSort((s) => (s && s.key === key ? { key, dir: s.dir === "asc" ? "desc" : "asc" } : { key, dir: "asc" }));
+    const all = useMemo(() => processCollection(items, { query, sort, searchKeys: config.searchKeys, search: config.search, filter: config.filter }), [items, query, sort, config.searchKeys, config.search, config.filter]);
+    const size = config.pageSize && config.pageSize > 0 ? config.pageSize : all.length || 1;
+    const pageCount = Math.max(1, Math.ceil(all.length / size));
+    const clamped = Math.min(page, pageCount - 1);
+    const pageItems = config.pageSize ? all.slice(clamped * size, clamped * size + size) : all;
+    return {
+        items: pageItems,
+        all,
+        query,
+        setQuery,
+        sort,
+        toggleSort,
+        setSort,
+        page: clamped,
+        setPage,
+        nextPage: () => setPage((p) => Math.min(p + 1, pageCount - 1)),
+        prevPage: () => setPage((p) => Math.max(p - 1, 0)),
+        pageCount,
+        total: all.length,
+        isEmpty: all.length === 0,
+    };
+}

package/dist/data/useCollection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/data/useCollection.test.js

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest";
+import { processCollection } from "./useCollection";
+const rows = [
+    { name: "Alice", age: 30 },
+    { name: "bob", age: 25 },
+    { name: "Carol", age: 40 },
+];
+describe("processCollection", () => {
+    it("filters, then case-insensitive searches, then sorts (numeric-aware)", () => {
+        const sorted = processCollection(rows, { sort: { key: "age", dir: "asc" } });
+        expect(sorted.map((r) => r.age)).toEqual([25, 30, 40]);
+        const desc = processCollection(rows, { sort: { key: "name", dir: "desc" } });
+        expect(desc.map((r) => r.name)).toEqual(["Carol", "bob", "Alice"]);
+        const searched = processCollection(rows, { query: "car", searchKeys: ["name"] });
+        expect(searched).toEqual([{ name: "Carol", age: 40 }]);
+        const filtered = processCollection(rows, { filter: (r) => r.age >= 30, query: "" });
+        expect(filtered.map((r) => r.name).sort()).toEqual(["Alice", "Carol"]);
+    });
+    it("does not mutate the input array", () => {
+        const copy = rows.slice();
+        processCollection(rows, { sort: { key: "age", dir: "desc" } });
+        expect(rows).toEqual(copy);
+    });
+    it("searches all string/number fields when no searchKeys given", () => {
+        expect(processCollection(rows, { query: "40" })).toEqual([{ name: "Carol", age: 40 }]);
+    });
+});

package/dist/data/useEventSource.d.ts

@@ -0,0 +1,15 @@
+export type StreamStatus = "connecting" | "open" | "error" | "closed";
+export interface EventSourceState<T> {
+    /** Last message, JSON-parsed when possible (else the raw string). */
+    data: T | undefined;
+    status: StreamStatus;
+    error: Error | null;
+}
+export interface UseEventSourceOptions {
+    enabled?: boolean;
+    /** Send cookies with the request (same-origin auth). */
+    withCredentials?: boolean;
+    /** Listen for a named event instead of the default `message`. */
+    event?: string;
+}
+export declare function useEventSource<T = unknown>(url?: string, opts?: UseEventSourceOptions): EventSourceState<T>;