@riktajs/react 0.10.3

package/dist/index.d.ts

@@ -0,0 +1,609 @@
+import * as react from 'react';
+import { FC } from 'react';
+
+/**
+ * SSR data structure passed from server to client
+ * via window.__SSR_DATA__
+ */
+interface SsrData<T = unknown> {
+    /** Initial data rendered on server */
+    data: T;
+    /** Current URL path */
+    url: string;
+    /** HTTP status code */
+    status?: number;
+    /** Additional metadata */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Router context value interface
+ */
+interface RouterContextValue {
+    /** Current URL path */
+    pathname: string;
+    /** Current search params string (without ?) */
+    search: string;
+    /** Full URL */
+    href: string;
+    /** Navigate to a new URL */
+    navigate: (url: string, options?: NavigateOptions) => void;
+    /** Extracted route params (e.g., { id: '123' } for /item/:id) */
+    params: Record<string, string>;
+    /** Update route params (used internally by RiktaProvider) */
+    setParams: (params: Record<string, string>) => void;
+}
+/**
+ * Navigation options
+ */
+interface NavigateOptions {
+    /** Replace current history entry instead of pushing */
+    replace?: boolean;
+    /** Scroll to top after navigation */
+    scroll?: boolean;
+    /** Additional state to store in history */
+    state?: unknown;
+}
+/**
+ * Result type for server actions
+ */
+interface ActionResult<T = unknown> {
+    /** Whether the action was successful */
+    success: boolean;
+    /** Response data on success */
+    data?: T;
+    /** Error message on failure */
+    error?: string;
+    /** Field-specific validation errors */
+    fieldErrors?: Record<string, string[]>;
+}
+/**
+ * Fetch state for useFetch hook
+ */
+interface FetchState<T = unknown> {
+    /** Fetched data */
+    data: T | null;
+    /** Whether fetch is in progress */
+    loading: boolean;
+    /** Error message if fetch failed */
+    error: string | null;
+    /** Manually refetch data */
+    refetch: () => Promise<void>;
+}
+/**
+ * Action state for useAction hook
+ */
+interface ActionState<TInput = unknown, TResult = unknown> {
+    /** Execute the action */
+    execute: (input: TInput) => Promise<ActionResult<TResult>>;
+    /** Whether action is executing */
+    pending: boolean;
+    /** Last action result */
+    result: ActionResult<TResult> | null;
+    /** Reset action state */
+    reset: () => void;
+}
+/**
+ * Link component props
+ */
+interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+    /** Target URL */
+    href: string;
+    /** Replace history entry instead of push */
+    replace?: boolean;
+    /** Scroll to top after navigation */
+    scroll?: boolean;
+    /** Prefetch the linked page (future enhancement) */
+    prefetch?: boolean;
+    /** Additional state to pass to navigation */
+    state?: unknown;
+    /** Children elements */
+    children: React.ReactNode;
+}
+/**
+ * RiktaProvider props
+ */
+interface RiktaProviderProps {
+    /** Initial SSR data from server */
+    ssrData?: SsrData;
+    /** Initial route params extracted from URL */
+    initialParams?: Record<string, string>;
+    /** Children elements */
+    children: React.ReactNode;
+}
+/**
+ * Hydration state
+ */
+interface HydrationState {
+    /** Whether the app has hydrated on client */
+    isHydrated: boolean;
+    /** Whether currently running on server */
+    isServer: boolean;
+}
+declare global {
+    interface Window {
+        __SSR_DATA__?: SsrData;
+    }
+}
+
+/**
+ * React context for router state
+ * Provides navigation utilities and current location info
+ */
+declare const RouterContext: react.Context<RouterContextValue>;
+
+/**
+ * React context for SSR data
+ * Holds the server-rendered data passed via window.__SSR_DATA__
+ */
+declare const SsrContext: react.Context<SsrData<unknown> | null>;
+
+/**
+ * RiktaProvider - Main provider component for Rikta React utilities
+ *
+ * Provides routing context, SSR data, and navigation utilities to the app.
+ *
+ * @example
+ * ```tsx
+ * // In entry-client.tsx
+ * import { RiktaProvider } from '@riktajs/react';
+ *
+ * hydrateRoot(
+ *   document.getElementById('root')!,
+ *   <RiktaProvider>
+ *     <App />
+ *   </RiktaProvider>
+ * );
+ * ```
+ */
+declare const RiktaProvider: FC<RiktaProviderProps>;
+
+/**
+ * Link component for client-side navigation
+ *
+ * Renders an anchor tag that uses the History API for navigation
+ * instead of causing a full page reload.
+ *
+ * @example
+ * ```tsx
+ * import { Link } from '@riktajs/react';
+ *
+ * function Nav() {
+ *   return (
+ *     <nav>
+ *       <Link href="/">Home</Link>
+ *       <Link href="/about">About</Link>
+ *       <Link href="/items/123">Item 123</Link>
+ *     </nav>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With options
+ * <Link href="/dashboard" replace scroll={false}>
+ *   Dashboard
+ * </Link>
+ * ```
+ */
+declare const Link: FC<LinkProps>;
+
+/**
+ * Hook for programmatic navigation
+ *
+ * @returns Object with navigate function and current location info
+ *
+ * @example
+ * ```tsx
+ * import { useNavigation } from '@riktajs/react';
+ *
+ * function MyComponent() {
+ *   const { navigate, pathname } = useNavigation();
+ *
+ *   const handleSubmit = async () => {
+ *     await saveData();
+ *     navigate('/success');
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleSubmit}>
+ *       Submit (current path: {pathname})
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With options
+ * const { navigate } = useNavigation();
+ *
+ * // Replace history entry (for redirects)
+ * navigate('/login', { replace: true });
+ *
+ * // Don't scroll to top
+ * navigate('/next', { scroll: false });
+ *
+ * // Pass state
+ * navigate('/edit', { state: { from: 'list' } });
+ * ```
+ */
+declare function useNavigation(): {
+    /** Navigate to a new URL */
+    navigate: (url: string, options?: NavigateOptions) => void;
+    /** Current pathname */
+    pathname: string;
+    /** Current search string (without ?) */
+    search: string;
+    /** Full href */
+    href: string;
+};
+
+/**
+ * Hook to access route parameters
+ *
+ * Route parameters are extracted from the URL path by the server
+ * and passed via SSR data. They're stored in the RouterContext.
+ *
+ * @returns Object with route parameter values
+ *
+ * @example
+ * ```tsx
+ * // For route /item/:id
+ * import { useParams } from '@riktajs/react';
+ *
+ * function ItemPage() {
+ *   const { id } = useParams<{ id: string }>();
+ *
+ *   return <h1>Item {id}</h1>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple params - /users/:userId/posts/:postId
+ * function PostPage() {
+ *   const { userId, postId } = useParams<{ userId: string; postId: string }>();
+ *
+ *   return <h1>Post {postId} by User {userId}</h1>;
+ * }
+ * ```
+ */
+declare function useParams<T extends Record<string, string> = Record<string, string>>(): T;
+
+/**
+ * Hook to access and manipulate URL search parameters
+ *
+ * @returns Tuple of [URLSearchParams, setSearchParams function]
+ *
+ * @example
+ * ```tsx
+ * import { useSearchParams } from '@riktajs/react';
+ *
+ * function SearchPage() {
+ *   const [searchParams, setSearchParams] = useSearchParams();
+ *   const query = searchParams.get('q') ?? '';
+ *   const page = parseInt(searchParams.get('page') ?? '1', 10);
+ *
+ *   const handleSearch = (newQuery: string) => {
+ *     setSearchParams({ q: newQuery, page: '1' });
+ *   };
+ *
+ *   const handleNextPage = () => {
+ *     setSearchParams({ q: query, page: String(page + 1) });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         value={query}
+ *         onChange={(e) => handleSearch(e.target.value)}
+ *       />
+ *       <button onClick={handleNextPage}>Next Page</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useSearchParams(): [URLSearchParams, (params: Record<string, string> | URLSearchParams) => void];
+
+/**
+ * Location object returned by useLocation
+ */
+interface Location {
+    /** Current pathname (e.g., /items/123) */
+    pathname: string;
+    /** Current search string without ? (e.g., page=2&sort=asc) */
+    search: string;
+    /** Full href */
+    href: string;
+    /** Parsed search params */
+    searchParams: URLSearchParams;
+}
+/**
+ * Hook to access current location information
+ *
+ * @returns Location object with pathname, search, href, and searchParams
+ *
+ * @example
+ * ```tsx
+ * import { useLocation } from '@riktajs/react';
+ *
+ * function Breadcrumbs() {
+ *   const location = useLocation();
+ *
+ *   return (
+ *     <nav>
+ *       Current path: {location.pathname}
+ *       {location.search && <span>?{location.search}</span>}
+ *     </nav>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Access search params
+ * function FilterDisplay() {
+ *   const { searchParams } = useLocation();
+ *   const filter = searchParams.get('filter');
+ *
+ *   return filter ? <span>Filtered by: {filter}</span> : null;
+ * }
+ * ```
+ */
+declare function useLocation(): Location;
+
+/**
+ * Hook to access SSR data passed from server
+ *
+ * SSR data is passed via window.__SSR_DATA__ and contains
+ * the initial data rendered on the server.
+ *
+ * @returns SSR data object or null if not available
+ *
+ * @example
+ * ```tsx
+ * import { useSsrData } from '@riktajs/react';
+ *
+ * interface PageData {
+ *   title: string;
+ *   items: Array<{ id: string; name: string }>;
+ * }
+ *
+ * function ItemList() {
+ *   const ssrData = useSsrData<PageData>();
+ *
+ *   if (!ssrData) {
+ *     return <div>Loading...</div>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <h1>{ssrData.data.title}</h1>
+ *       <ul>
+ *         {ssrData.data.items.map(item => (
+ *           <li key={item.id}>{item.name}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Access just the data
+ * function MyComponent() {
+ *   const ssrData = useSsrData<{ user: User }>();
+ *   const user = ssrData?.data.user;
+ *
+ *   return user ? <UserProfile user={user} /> : <LoginPrompt />;
+ * }
+ * ```
+ */
+declare function useSsrData<T = unknown>(): SsrData<T> | null;
+
+/**
+ * Hook to track hydration state
+ *
+ * Useful for rendering different content during SSR vs after hydration,
+ * or for avoiding hydration mismatches.
+ *
+ * @returns Hydration state object
+ *
+ * @example
+ * ```tsx
+ * import { useHydration } from '@riktajs/react';
+ *
+ * function TimeDisplay() {
+ *   const { isHydrated, isServer } = useHydration();
+ *
+ *   // On server and initial render, show static content
+ *   // After hydration, show dynamic content
+ *   if (!isHydrated) {
+ *     return <span>Loading time...</span>;
+ *   }
+ *
+ *   return <span>{new Date().toLocaleTimeString()}</span>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Avoid hydration mismatch with client-only content
+ * function ClientOnlyComponent() {
+ *   const { isHydrated } = useHydration();
+ *
+ *   if (!isHydrated) {
+ *     return null; // Or a placeholder
+ *   }
+ *
+ *   return <SomeClientOnlyLibrary />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Conditional rendering based on environment
+ * function DebugPanel() {
+ *   const { isServer } = useHydration();
+ *
+ *   // Never render on server, only after client hydration
+ *   if (isServer) return null;
+ *
+ *   return <DevTools />;
+ * }
+ * ```
+ */
+declare function useHydration(): HydrationState;
+
+/**
+ * Options for useFetch hook
+ */
+interface UseFetchOptions extends Omit<RequestInit, 'body'> {
+    /** Skip initial fetch (useful for conditional fetching) */
+    skip?: boolean;
+    /** Dependencies that trigger refetch when changed */
+    deps?: unknown[];
+    /** Transform response before setting data */
+    transform?: (data: unknown) => unknown;
+}
+/**
+ * Hook for data fetching with loading and error states
+ *
+ * @param url URL to fetch from
+ * @param options Fetch options
+ * @returns Fetch state with data, loading, error, and refetch function
+ *
+ * @example
+ * ```tsx
+ * import { useFetch } from '@riktajs/react';
+ *
+ * interface User {
+ *   id: string;
+ *   name: string;
+ * }
+ *
+ * function UserProfile({ userId }: { userId: string }) {
+ *   const { data, loading, error, refetch } = useFetch<User>(
+ *     `/api/users/${userId}`
+ *   );
+ *
+ *   if (loading) return <Spinner />;
+ *   if (error) return <Error message={error} />;
+ *   if (!data) return null;
+ *
+ *   return (
+ *     <div>
+ *       <h1>{data.name}</h1>
+ *       <button onClick={refetch}>Refresh</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With options
+ * const { data } = useFetch<Item[]>('/api/items', {
+ *   headers: { 'Authorization': `Bearer ${token}` },
+ *   deps: [token], // Refetch when token changes
+ *   skip: !token,  // Don't fetch until we have a token
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With transform
+ * const { data } = useFetch<{ results: Item[] }>('/api/search', {
+ *   transform: (res) => res.results, // Extract just the results array
+ * });
+ * ```
+ */
+declare function useFetch<T = unknown>(url: string, options?: UseFetchOptions): FetchState<T>;
+
+/**
+ * Options for useAction hook
+ */
+interface UseActionOptions<TResult = unknown> {
+    /** Callback on successful action */
+    onSuccess?: (result: TResult) => void;
+    /** Callback on action error */
+    onError?: (error: string) => void;
+    /** HTTP method to use */
+    method?: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Additional headers */
+    headers?: Record<string, string>;
+}
+/**
+ * Hook for executing server actions (form submissions, mutations)
+ *
+ * @param url URL to send the action to
+ * @param options Action options
+ * @returns Action state with execute, pending, result, and reset
+ *
+ * @example
+ * ```tsx
+ * import { useAction } from '@riktajs/react';
+ *
+ * interface CreateItemInput {
+ *   name: string;
+ *   price: number;
+ * }
+ *
+ * interface Item {
+ *   id: string;
+ *   name: string;
+ *   price: number;
+ * }
+ *
+ * function CreateItemForm() {
+ *   const { execute, pending, result } = useAction<CreateItemInput, Item>(
+ *     '/api/items',
+ *     {
+ *       onSuccess: (item) => {
+ *         console.log('Created item:', item);
+ *       },
+ *     }
+ *   );
+ *
+ *   const handleSubmit = async (e: FormEvent) => {
+ *     e.preventDefault();
+ *     const formData = new FormData(e.target as HTMLFormElement);
+ *     await execute({
+ *       name: formData.get('name') as string,
+ *       price: Number(formData.get('price')),
+ *     });
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <input name="name" required />
+ *       <input name="price" type="number" required />
+ *       <button disabled={pending}>
+ *         {pending ? 'Creating...' : 'Create Item'}
+ *       </button>
+ *       {result?.error && <p className="error">{result.error}</p>}
+ *       {result?.fieldErrors?.name && (
+ *         <p className="error">{result.fieldErrors.name[0]}</p>
+ *       )}
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // DELETE action
+ * const { execute, pending } = useAction<{ id: string }, void>(
+ *   '/api/items',
+ *   { method: 'DELETE' }
+ * );
+ *
+ * const handleDelete = () => execute({ id: itemId });
+ * ```
+ */
+declare function useAction<TInput = unknown, TResult = unknown>(url: string, options?: UseActionOptions<TResult>): ActionState<TInput, TResult>;
+
+export { type ActionResult, type ActionState, type FetchState, type HydrationState, Link, type LinkProps, type Location, type NavigateOptions, RiktaProvider, type RiktaProviderProps, RouterContext, type RouterContextValue, SsrContext, type SsrData, type UseActionOptions, type UseFetchOptions, useAction, useFetch, useHydration, useLocation, useNavigation, useParams, useSearchParams, useSsrData };