@bazza-ui/react 0.0.0 → 0.1.0-canary.2

package/dist/adapters/index.d.cts

@@ -0,0 +1,363 @@
+import * as React from 'react';
+import { a2 as NodeDef, Z as InitialQueryBehavior, a1 as LoaderComponentProps, a4 as QueryDependentLoaderConfig, ah as StaticLoaderConfig, t as AsyncLoaderResult } from '../types-9vS1uLIK.cjs';
+import '../events-BPr8sRGH.cjs';
+
+/**
+ * SWR result shape (subset of SWRResponse).
+ * This allows the adapter to work without requiring `swr` as a dependency.
+ */
+interface SWRResult<TData, TError = Error> {
+    data: TData | undefined;
+    error: TError | undefined;
+    isLoading?: boolean;
+    isValidating: boolean;
+    isPaused?: boolean;
+    mutate: (...args: unknown[]) => unknown;
+}
+/**
+ * Converts an SWR result to an AsyncLoaderResult.
+ */
+declare function toAsyncLoaderResultFromSWR<TData, TError = Error>(result: SWRResult<TData, TError>): AsyncLoaderResult<TData, SWRResult<TData, TError>>;
+/**
+ * Props for creating a static SWR loader component.
+ */
+interface CreateSWRStaticLoaderProps {
+    /** Hook that returns an SWR result. */
+    useSWR: () => SWRResult<NodeDef[]>;
+    /**
+     * When to trigger the loader:
+     * - 'eager': Load when root menu opens
+     * - 'lazy': Load when submenu opens (default)
+     */
+    loadStrategy?: 'eager' | 'lazy';
+}
+/**
+ * Creates a static loader configuration backed by SWR.
+ */
+declare function createSWRStaticLoader(props: CreateSWRStaticLoaderProps): StaticLoaderConfig;
+/**
+ * Props for creating a query-dependent SWR loader component.
+ */
+interface CreateSWRQueryLoaderProps {
+    /**
+     * Hook that returns an SWR result based on the search query.
+     * `options.enabled` can be used to derive a `null` key and disable fetching.
+     */
+    useSWR: (query: string, options?: {
+        enabled: boolean;
+    }) => SWRResult<NodeDef[]>;
+    /**
+     * Minimum query length before fetching.
+     * @default 1
+     */
+    minQueryLength?: number;
+    /**
+     * Initial query behavior before user input reaches minQueryLength.
+     * Defaults to fetching with an empty query.
+     */
+    initialQueryBehavior?: InitialQueryBehavior | false;
+    /**
+     * @deprecated Use `initialQueryBehavior` instead.
+     */
+    initialQuery?: string;
+    /**
+     * When to trigger the loader:
+     * - 'eager': Load when root menu opens (good for deep search)
+     * - 'lazy': Load when submenu opens (default)
+     * @default 'lazy'
+     */
+    loadStrategy?: 'eager' | 'lazy';
+    /**
+     * What to show when query is below minQueryLength.
+     * @default 'empty'
+     */
+    belowMinBehavior?: 'empty' | 'placeholder';
+    /**
+     * Placeholder nodes shown when query is below minQueryLength.
+     */
+    placeholderNodes?: NodeDef[];
+}
+/**
+ * Creates a query-dependent loader configuration backed by SWR.
+ */
+declare function createSWRQueryLoader(props: CreateSWRQueryLoaderProps): QueryDependentLoaderConfig;
+/**
+ * Creates a loader component that wraps an SWR hook.
+ */
+declare function createSWRLoaderComponent(useSWRFn: (query: string) => SWRResult<NodeDef[]>): React.FC<LoaderComponentProps>;
+
+/**
+ * TanStack Query result shape (subset of UseQueryResult).
+ * This allows the adapter to work without requiring @tanstack/react-query as a dependency.
+ */
+interface TanStackQueryResult<TData, TError = Error> {
+    /** TanStack status (`pending` | `error` | `success`) */
+    status?: 'pending' | 'error' | 'success';
+    /** TanStack fetch status (`fetching` | `paused` | `idle`) */
+    fetchStatus?: 'fetching' | 'paused' | 'idle';
+    data: TData | undefined;
+    error: TError | null | undefined;
+    /** v5: true when first fetch is in-flight */
+    isLoading?: boolean;
+    /** v5: true when status is pending */
+    isPending?: boolean;
+    /** true when status is success */
+    isSuccess?: boolean;
+    /** true when status is error */
+    isError?: boolean;
+    /** true while any fetch is in-flight */
+    isFetching?: boolean;
+    /** true while background refetch is in-flight */
+    isRefetching?: boolean;
+    /** true when fetch is paused */
+    isPaused?: boolean;
+    /** true once query has fetched at least once */
+    isFetched?: boolean;
+    refetch: () => unknown;
+}
+/**
+ * Converts a TanStack Query result to an AsyncLoaderResult.
+ * Use this to wrap your useQuery hook result.
+ *
+ * @example
+ * ```tsx
+ * function MyLoader({ query, children }) {
+ *   const result = useQuery({
+ *     queryKey: ['items', query],
+ *     queryFn: () => fetchItems(query),
+ *   })
+ *   return children(toAsyncLoaderResult(result))
+ * }
+ * ```
+ */
+declare function toAsyncLoaderResult<TData, TError = Error>(result: TanStackQueryResult<TData, TError>): AsyncLoaderResult<TData, TanStackQueryResult<TData, TError>>;
+/**
+ * Props for creating a static loader component.
+ */
+interface CreateStaticLoaderProps {
+    /**
+     * Hook that returns a TanStack Query result.
+     * This hook will be called inside the loader component.
+     */
+    useQuery: () => TanStackQueryResult<NodeDef[]>;
+    /**
+     * When to trigger the loader:
+     * - 'eager': Load when root menu opens
+     * - 'lazy': Load when submenu opens (default)
+     */
+    loadStrategy?: 'eager' | 'lazy';
+}
+/**
+ * Creates a static loader configuration for use with async menus.
+ * The hook is called inside a component, so it follows React's rules of hooks.
+ *
+ * @example
+ * ```tsx
+ * const recentFilesLoader = createStaticLoader({
+ *   useQuery: () => useQuery({
+ *     queryKey: ['recent-files'],
+ *     queryFn: fetchRecentFiles,
+ *     staleTime: 5 * 60 * 1000,
+ *   }),
+ * })
+ *
+ * // Use in submenu
+ * {
+ *   kind: 'submenu',
+ *   value: 'Recent Files',
+ *   asyncNodes: {
+ *     ...recentFilesLoader,
+ *     loadStrategy: 'eager',
+ *   },
+ *   render: ...
+ * }
+ * ```
+ */
+declare function createStaticLoader(props: CreateStaticLoaderProps): StaticLoaderConfig;
+/**
+ * Props for creating a query-dependent loader component.
+ */
+interface CreateQueryLoaderProps {
+    /**
+     * Hook that returns a TanStack Query result based on the search query.
+     * This hook will be called inside the loader component with the current query.
+     */
+    useQuery: (query: string, options?: {
+        enabled: boolean;
+    }) => TanStackQueryResult<NodeDef[]>;
+    /**
+     * Minimum query length before fetching.
+     * @default 1
+     */
+    minQueryLength?: number;
+    /**
+     * Initial query behavior before user input reaches minQueryLength.
+     * Defaults to fetching with an empty query.
+     */
+    initialQueryBehavior?: InitialQueryBehavior | false;
+    /**
+     * @deprecated Use `initialQueryBehavior` instead.
+     */
+    initialQuery?: string;
+    /**
+     * When to trigger the loader:
+     * - 'eager': Load when root menu opens (good for deep search)
+     * - 'lazy': Load when submenu opens (default)
+     * @default 'lazy'
+     */
+    loadStrategy?: 'eager' | 'lazy';
+    /**
+     * What to show when query is below minQueryLength.
+     * @default 'empty'
+     */
+    belowMinBehavior?: 'empty' | 'placeholder';
+    /**
+     * Placeholder nodes shown when query is below minQueryLength.
+     */
+    placeholderNodes?: NodeDef[];
+}
+/**
+ * Creates a query-dependent loader configuration for use with async menus.
+ * The loader will re-fetch when the search query changes.
+ *
+ * @example
+ * ```tsx
+ * const searchLoader = createQueryLoader({
+ *   useQuery: (query, options) => useQuery({
+ *     queryKey: ['search', query],
+ *     queryFn: () => searchItems(query),
+ *     enabled: options?.enabled,
+ *   }),
+ *   minQueryLength: 2,
+ * })
+ *
+ * // Use in submenu
+ * {
+ *   kind: 'submenu',
+ *   value: 'Search',
+ *   includeInDeepSearch: true,
+ *   asyncNodes: searchLoader,
+ *   render: ...
+ * }
+ * ```
+ */
+declare function createQueryLoader(props: CreateQueryLoaderProps): QueryDependentLoaderConfig;
+/**
+ * Creates a loader component that wraps a TanStack Query hook.
+ * This is a lower-level utility for custom loader implementations.
+ *
+ * @example
+ * ```tsx
+ * const MyLoader = createLoaderComponent((query) =>
+ *   useQuery({
+ *     queryKey: ['items', query],
+ *     queryFn: () => fetchItems(query),
+ *   })
+ * )
+ * ```
+ */
+declare function createLoaderComponent(useQueryFn: (query: string) => TanStackQueryResult<NodeDef[]>): React.FC<LoaderComponentProps>;
+
+/**
+ * Props for creating a static loader with vanilla fetch.
+ */
+interface CreateVanillaStaticLoaderProps {
+    /**
+     * Async function that fetches the menu items.
+     */
+    fetcher: () => Promise<NodeDef[]>;
+    /**
+     * When to trigger the loader:
+     * - 'eager': Load when root menu opens
+     * - 'lazy': Load when submenu opens (default)
+     */
+    loadStrategy?: 'eager' | 'lazy';
+}
+/**
+ * Creates a static loader configuration using plain fetch/promises.
+ * No external data library required.
+ *
+ * @example
+ * ```tsx
+ * const recentFilesLoader = createVanillaStaticLoader({
+ *   fetcher: async () => {
+ *     const res = await fetch('/api/recent-files')
+ *     const data = await res.json()
+ *     return data.map(file => ({
+ *       kind: 'item',
+ *       value: file.name,
+ *       render: ...
+ *     }))
+ *   },
+ * })
+ * ```
+ */
+declare function createVanillaStaticLoader(props: CreateVanillaStaticLoaderProps): StaticLoaderConfig;
+/**
+ * Props for creating a query-dependent loader with vanilla fetch.
+ */
+interface CreateVanillaQueryLoaderProps {
+    /**
+     * Async function that fetches menu items based on the search query.
+     * Receives an optional `signal` that is aborted when a newer query is issued,
+     * allowing you to cancel in-flight requests (e.g. pass it to `fetch()`).
+     */
+    fetcher: (query: string, options?: {
+        signal?: AbortSignal;
+    }) => Promise<NodeDef[]>;
+    /**
+     * Minimum query length before fetching.
+     * @default 1
+     */
+    minQueryLength?: number;
+    /**
+     * Initial query behavior before user input reaches minQueryLength.
+     * Defaults to fetching with an empty query.
+     */
+    initialQueryBehavior?: InitialQueryBehavior | false;
+    /**
+     * @deprecated Use `initialQueryBehavior` instead.
+     */
+    initialQuery?: string;
+    /**
+     * When to trigger the loader:
+     * - 'eager': Load when root menu opens (good for deep search)
+     * - 'lazy': Load when submenu opens (default)
+     * @default 'lazy'
+     */
+    loadStrategy?: 'eager' | 'lazy';
+    /**
+     * What to show when query is below minQueryLength.
+     * @default 'empty'
+     */
+    belowMinBehavior?: 'empty' | 'placeholder';
+    /**
+     * Placeholder nodes shown when query is below minQueryLength.
+     */
+    placeholderNodes?: NodeDef[];
+}
+/**
+ * Creates a query-dependent loader configuration using plain fetch/promises.
+ * No external data library required.
+ *
+ * @example
+ * ```tsx
+ * const searchLoader = createVanillaQueryLoader({
+ *   fetcher: async (query, options) => {
+ *     const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`, {
+ *       signal: options?.signal, // aborts when a newer query is issued
+ *     })
+ *     const data = await res.json()
+ *     return data.map(item => ({
+ *       kind: 'item',
+ *       value: item.name,
+ *       render: ...
+ *     }))
+ *   },
+ *   minQueryLength: 2,
+ * })
+ * ```
+ */
+declare function createVanillaQueryLoader(props: CreateVanillaQueryLoaderProps): QueryDependentLoaderConfig;
+
+export { type CreateQueryLoaderProps, type CreateSWRQueryLoaderProps, type CreateSWRStaticLoaderProps, type CreateStaticLoaderProps, type CreateVanillaQueryLoaderProps, type CreateVanillaStaticLoaderProps, type SWRResult, type TanStackQueryResult, createLoaderComponent, createQueryLoader, createSWRLoaderComponent, createSWRQueryLoader, createSWRStaticLoader, createStaticLoader, createVanillaQueryLoader, createVanillaStaticLoader, toAsyncLoaderResult, toAsyncLoaderResultFromSWR };