@riktajs/react 0.11.5 → 0.11.6

package/dist/index.d.cts

@@ -1,6 +1,3 @@
-import * as react from 'react';
-import { FC } from 'react';
-
 /**
  * SSR data structure passed from server to client
  * via window.__SSR_DATA__
@@ -19,36 +16,6 @@ interface SsrData<T = unknown> {
     /** 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 | Promise<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;
-    /** Whether a navigation is in progress */
-    isNavigating?: boolean;
-}
-/**
- * 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
  */
@@ -88,34 +55,6 @@ interface ActionState<TInput = unknown, TResult = unknown> {
     /** 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
  */
@@ -132,125 +71,147 @@ declare global {
 }
 
 /**
- * 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
+ * Get SSR data from window.__SSR_DATA__
  *
- * Provides routing context, SSR data, and navigation utilities to the app.
- * Automatically fetches new page data during client-side navigation.
+ * This is a pure utility function (not a React hook) that reads
+ * the SSR data passed from the server. It can be called anywhere
+ * in your application without needing a Provider wrapper.
  *
- * @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
+ * The data is cached after first read for performance.
  *
- * Renders an anchor tag that uses the History API for navigation
- * instead of causing a full page reload.
+ * @returns SSR data object or null if not available
  *
  * @example
  * ```tsx
- * import { Link } from '@riktajs/react';
+ * import { getSsrData } from '@riktajs/react';
+ *
+ * interface PageData {
+ *   title: string;
+ *   items: Array<{ id: string; name: string }>;
+ * }
+ *
+ * function ItemList() {
+ *   const ssrData = getSsrData<PageData>();
+ *
+ *   if (!ssrData) {
+ *     return <div>Loading...</div>;
+ *   }
  *
- * function Nav() {
  *   return (
- *     <nav>
- *       <Link href="/">Home</Link>
- *       <Link href="/about">About</Link>
- *       <Link href="/items/123">Item 123</Link>
- *     </nav>
+ *     <div>
+ *       <h1>{ssrData.data.title}</h1>
+ *       <ul>
+ *         {ssrData.data.items.map(item => (
+ *           <li key={item.id}>{item.name}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
  *   );
  * }
  * ```
  *
  * @example
  * ```tsx
- * // With options
- * <Link href="/dashboard" replace scroll={false}>
- *   Dashboard
- * </Link>
+ * // Access directly without needing Provider
+ * const ssrData = getSsrData<{ user: User }>();
+ * const user = ssrData?.data.user;
  * ```
  */
-declare const Link: FC<LinkProps>;
+declare function getSsrData<T = unknown>(): SsrData<T> | null;
+/**
+ * Clear the SSR data cache
+ * Useful for testing or when SSR data changes dynamically
+ */
+declare function clearSsrDataCache(): void;
+/**
+ * Set SSR data manually (for testing or server-side rendering)
+ *
+ * @param data - SSR data to set, or null to clear
+ */
+declare function setSsrData(data: SsrData | null): void;
 
 /**
- * Hook for programmatic navigation
+ * Options for navigation
+ */
+interface NavigateOptions {
+    /** Replace current history entry instead of pushing (uses location.replace) */
+    replace?: boolean;
+}
+/**
+ * Navigate function type
  *
- * @returns Object with navigate function and current location info
+ * @param path - The path to navigate to
+ * @param paramsOrOptions - Either query params object or navigate options
+ * @param options - Navigate options (when params are provided)
+ */
+type NavigateFn = {
+    (path: string, options?: NavigateOptions): void;
+    (path: string, params: Record<string, string | number | boolean | undefined | null>, options?: NavigateOptions): void;
+};
+/**
+ * Hook for programmatic navigation using native browser APIs
+ *
+ * This hook provides a simple way to navigate between pages using
+ * standard browser navigation (full page loads for SSR pages).
+ *
+ * @returns Navigate function
  *
  * @example
  * ```tsx
- * import { useNavigation } from '@riktajs/react';
+ * import { useNavigate } from '@riktajs/react';
  *
  * function MyComponent() {
- *   const { navigate, pathname } = useNavigation();
+ *   const navigate = useNavigate();
  *
- *   const handleSubmit = async () => {
- *     await saveData();
- *     navigate('/success');
+ *   const handleClick = () => {
+ *     // Simple navigation
+ *     navigate('/dashboard');
  *   };
  *
- *   return (
- *     <button onClick={handleSubmit}>
- *       Submit (current path: {pathname})
- *     </button>
- *   );
+ *   const handleSearch = (query: string) => {
+ *     // Navigation with query params
+ *     navigate('/search', { q: query, page: 1 });
+ *     // Results in: /search?q=query&page=1
+ *   };
+ *
+ *   const handleLogin = () => {
+ *     // Replace current history entry (for redirects)
+ *     navigate('/login', { replace: true });
+ *   };
+ *
+ *   const handleFilter = (filter: string) => {
+ *     // Params + options
+ *     navigate('/items', { filter, sort: 'name' }, { replace: true });
+ *   };
+ *
+ *   return <button onClick={handleClick}>Go to Dashboard</button>;
  * }
  * ```
  *
  * @example
  * ```tsx
- * // With options
- * const { navigate } = useNavigation();
- *
- * // Replace history entry (for redirects)
- * navigate('/login', { replace: true });
+ * // After form submission
+ * function CreateItemForm() {
+ *   const navigate = useNavigate();
  *
- * // Don't scroll to top
- * navigate('/next', { scroll: false });
+ *   const handleSubmit = async (data: FormData) => {
+ *     const result = await createItem(data);
+ *     if (result.success) {
+ *       navigate(`/items/${result.id}`);
+ *     }
+ *   };
  *
- * // Pass state
- * navigate('/edit', { state: { from: 'list' } });
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
  * ```
  */
-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;
-};
+declare function useNavigate(): NavigateFn;
 
 /**
- * Hook to access route parameters
+ * Hook to access route parameters from SSR data
  *
  * Route parameters are extracted from the URL path by the server
- * and passed via SSR data. They're stored in the RouterContext.
+ * and passed via SSR data. This hook reads them from the SSR data.
  *
  * @returns Object with route parameter values
  *
@@ -279,7 +240,11 @@ declare function useNavigation(): {
 declare function useParams<T extends Record<string, string> = Record<string, string>>(): T;
 
 /**
- * Hook to access and manipulate URL search parameters
+ * Hook to access and update URL search parameters using native browser APIs
+ *
+ * This hook provides a simple interface for reading and modifying URL query
+ * parameters. When updating params, it triggers a full page navigation to
+ * ensure SSR data is refreshed.
  *
  * @returns Tuple of [URLSearchParams, setSearchParams function]
  *
@@ -311,8 +276,30 @@ declare function useParams<T extends Record<string, string> = Record<string, str
  *   );
  * }
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Merge with existing params
+ * function FilterComponent() {
+ *   const [searchParams, setSearchParams] = useSearchParams();
+ *
+ *   const updateFilter = (filter: string) => {
+ *     // Get current params and update
+ *     const params = Object.fromEntries(searchParams.entries());
+ *     setSearchParams({ ...params, filter });
+ *   };
+ *
+ *   return (
+ *     <select onChange={(e) => updateFilter(e.target.value)}>
+ *       <option value="">All</option>
+ *       <option value="active">Active</option>
+ *       <option value="inactive">Inactive</option>
+ *     </select>
+ *   );
+ * }
+ * ```
  */
-declare function useSearchParams(): [URLSearchParams, (params: Record<string, string> | URLSearchParams) => void];
+declare function useSearchParams(): [URLSearchParams, (params: Record<string, string | number | boolean | undefined | null> | URLSearchParams) => void];
 
 /**
  * Location object returned by useLocation
@@ -328,7 +315,10 @@ interface Location {
     searchParams: URLSearchParams;
 }
 /**
- * Hook to access current location information
+ * Hook to access current location information using native browser APIs
+ *
+ * This hook reads directly from `window.location` and provides a convenient
+ * interface for accessing URL information.
  *
  * @returns Location object with pathname, search, href, and searchParams
  *
@@ -358,6 +348,21 @@ interface Location {
  *   return filter ? <span>Filtered by: {filter}</span> : null;
  * }
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Use pathname for conditional rendering
+ * function Navigation() {
+ *   const { pathname } = useLocation();
+ *
+ *   return (
+ *     <nav>
+ *       <a href="/" className={pathname === '/' ? 'active' : ''}>Home</a>
+ *       <a href="/about" className={pathname === '/about' ? 'active' : ''}>About</a>
+ *     </nav>
+ *   );
+ * }
+ * ```
  */
 declare function useLocation(): Location;
 
@@ -367,6 +372,9 @@ declare function useLocation(): Location;
  * SSR data is passed via window.__SSR_DATA__ and contains
  * the initial data rendered on the server.
  *
+ * Note: This is a simple wrapper around getSsrData() for
+ * familiarity. You can also use getSsrData() directly.
+ *
  * @returns SSR data object or null if not available
  *
  * @example
@@ -613,4 +621,4 @@ interface UseActionOptions<TResult = unknown> {
  */
 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 };
+export { type ActionResult, type ActionState, type FetchState, type HydrationState, type Location, type NavigateFn, type NavigateOptions, type SsrData, type UseActionOptions, type UseFetchOptions, clearSsrDataCache, getSsrData, setSsrData, useAction, useFetch, useHydration, useLocation, useNavigate, useParams, useSearchParams, useSsrData };