@riktajs/react 0.10.3

package/README.md

@@ -0,0 +1,368 @@
+# @riktajs/react
+
+React utilities for Rikta SSR framework. Provides hooks and components for routing, navigation, SSR data access, and server interactions.
+
+## Installation
+
+```bash
+npm install @riktajs/react
+# or
+pnpm add @riktajs/react
+# or
+yarn add @riktajs/react
+```
+
+## Quick Start
+
+Wrap your app with `RiktaProvider` to enable all features:
+
+```tsx
+// entry-client.tsx
+import { hydrateRoot } from 'react-dom/client';
+import { RiktaProvider } from '@riktajs/react';
+import App from './App';
+
+hydrateRoot(
+  document.getElementById('root')!,
+  <RiktaProvider>
+    <App />
+  </RiktaProvider>
+);
+```
+
+## Components
+
+### `<Link>`
+
+Client-side navigation link component that uses the History API instead of full page reloads.
+
+```tsx
+import { Link } from '@riktajs/react';
+
+function Navigation() {
+  return (
+    <nav>
+      <Link href="/">Home</Link>
+      <Link href="/about">About</Link>
+      <Link href="/items/123">Item 123</Link>
+      
+      {/* With options */}
+      <Link href="/dashboard" replace scroll={false}>
+        Dashboard
+      </Link>
+    </nav>
+  );
+}
+```
+
+**Props:**
+- `href` (required): Target URL
+- `replace`: Replace history entry instead of push
+- `scroll`: Scroll to top after navigation (default: `true`)
+- `state`: Additional state to pass to navigation
+- All standard `<a>` props are supported
+
+### `<RiktaProvider>`
+
+Root provider component that enables all Rikta React utilities.
+
+```tsx
+import { RiktaProvider } from '@riktajs/react';
+
+function App() {
+  return (
+    <RiktaProvider>
+      <YourApp />
+    </RiktaProvider>
+  );
+}
+```
+
+## Hooks
+
+### `useNavigation()`
+
+Programmatic navigation hook.
+
+```tsx
+import { useNavigation } from '@riktajs/react';
+
+function MyComponent() {
+  const { navigate, pathname } = useNavigation();
+
+  const handleSubmit = async () => {
+    await saveData();
+    navigate('/success');
+  };
+
+  // With options
+  navigate('/login', { replace: true });
+  navigate('/next', { scroll: false });
+  navigate('/edit', { state: { from: 'list' } });
+
+  return <button onClick={handleSubmit}>Submit</button>;
+}
+```
+
+### `useParams()`
+
+Access route parameters extracted from dynamic URLs.
+
+```tsx
+import { useParams } from '@riktajs/react';
+
+// For route /item/:id
+function ItemPage() {
+  const { id } = useParams<{ id: string }>();
+  
+  return <h1>Item {id}</h1>;
+}
+
+// Multiple params - /users/:userId/posts/:postId
+function PostPage() {
+  const { userId, postId } = useParams<{ userId: string; postId: string }>();
+  
+  return <h1>Post {postId} by User {userId}</h1>;
+}
+```
+
+### `useSearchParams()`
+
+Access and update URL search parameters.
+
+```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' });
+  };
+
+  return (
+    <input 
+      value={query} 
+      onChange={(e) => handleSearch(e.target.value)} 
+    />
+  );
+}
+```
+
+### `useLocation()`
+
+Get current location information.
+
+```tsx
+import { useLocation } from '@riktajs/react';
+
+function Breadcrumbs() {
+  const { pathname, search, searchParams } = useLocation();
+  
+  return (
+    <nav>
+      Current path: {pathname}
+      {search && <span>?{search}</span>}
+    </nav>
+  );
+}
+```
+
+### `useSsrData()`
+
+Access SSR data passed from server via `window.__SSR_DATA__`.
+
+```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>
+  );
+}
+```
+
+### `useHydration()`
+
+Track hydration state for client-only rendering.
+
+```tsx
+import { useHydration } from '@riktajs/react';
+
+function TimeDisplay() {
+  const { isHydrated, isServer } = useHydration();
+  
+  // Avoid hydration mismatch with dynamic content
+  if (!isHydrated) {
+    return <span>Loading time...</span>;
+  }
+  
+  return <span>{new Date().toLocaleTimeString()}</span>;
+}
+
+function ClientOnlyComponent() {
+  const { isHydrated } = useHydration();
+  
+  if (!isHydrated) return null;
+  
+  return <SomeClientOnlyLibrary />;
+}
+```
+
+### `useFetch()`
+
+Data fetching hook with loading and error states.
+
+```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>
+  );
+}
+
+// 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
+  transform: (res) => res.results, // Transform response
+});
+```
+
+### `useAction()`
+
+Execute server actions (form submissions, mutations).
+
+```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),
+      onError: (error) => console.error('Failed:', error),
+    }
+  );
+
+  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>}
+    </form>
+  );
+}
+
+// DELETE action
+const { execute, pending } = useAction<{ id: string }, void>(
+  '/api/items',
+  { method: 'DELETE' }
+);
+```
+
+## TypeScript
+
+All exports are fully typed. Import types as needed:
+
+```tsx
+import type {
+  SsrData,
+  RouterContextValue,
+  NavigateOptions,
+  ActionResult,
+  FetchState,
+  ActionState,
+  LinkProps,
+  HydrationState,
+  Location,
+} from '@riktajs/react';
+```
+
+## Integration with @riktajs/ssr
+
+This package is designed to work seamlessly with `@riktajs/ssr`. The SSR plugin automatically injects `window.__SSR_DATA__` which `RiktaProvider` picks up.
+
+```tsx
+// Server: page.controller.ts
+@Controller()
+export class PageController {
+  @Get('/item/:id')
+  @Render()
+  getItem(@Param('id') id: string) {
+    const item = getItemById(id);
+    return { item, params: { id } };
+  }
+}
+
+// Client: ItemPage.tsx
+function ItemPage() {
+  const ssrData = useSsrData<{ item: Item; params: { id: string } }>();
+  const { id } = useParams();
+  
+  return <h1>{ssrData?.data.item.name} (ID: {id})</h1>;
+}
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,316 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/context/RouterContext.ts
+var defaultRouterContext = {
+  pathname: "/",
+  search: "",
+  href: "/",
+  navigate: () => {
+    console.warn("[RiktaReact] Router context not initialized. Wrap your app with <RiktaProvider>");
+  },
+  params: {},
+  setParams: () => {
+  }
+};
+var RouterContext = react.createContext(defaultRouterContext);
+RouterContext.displayName = "RiktaRouterContext";
+var SsrContext = react.createContext(null);
+SsrContext.displayName = "RiktaSsrContext";
+function getLocationInfo() {
+  if (typeof window === "undefined") {
+    return { pathname: "/", search: "", href: "/" };
+  }
+  return {
+    pathname: window.location.pathname,
+    search: window.location.search.slice(1),
+    // Remove leading ?
+    href: window.location.href
+  };
+}
+function getSsrData() {
+  if (typeof window === "undefined") return void 0;
+  return window.__SSR_DATA__;
+}
+var RiktaProvider = ({
+  ssrData: initialSsrData,
+  initialParams = {},
+  children
+}) => {
+  const [ssrData] = react.useState(() => {
+    return initialSsrData ?? getSsrData() ?? null;
+  });
+  const [location, setLocation] = react.useState(getLocationInfo);
+  const [params, setParams] = react.useState(initialParams);
+  const navigate = react.useCallback((url, options = {}) => {
+    const { replace = false, scroll = true, state } = options;
+    if (typeof window === "undefined") return;
+    let targetUrl;
+    try {
+      targetUrl = new URL(url, window.location.origin);
+    } catch {
+      console.error(`[RiktaReact] Invalid URL: ${url}`);
+      return;
+    }
+    if (targetUrl.origin !== window.location.origin) {
+      window.location.href = url;
+      return;
+    }
+    if (replace) {
+      window.history.replaceState(state ?? null, "", targetUrl.href);
+    } else {
+      window.history.pushState(state ?? null, "", targetUrl.href);
+    }
+    setLocation({
+      pathname: targetUrl.pathname,
+      search: targetUrl.search.slice(1),
+      href: targetUrl.href
+    });
+    if (scroll) {
+      window.scrollTo(0, 0);
+    }
+    window.dispatchEvent(new PopStateEvent("popstate", { state }));
+  }, []);
+  react.useEffect(() => {
+    if (typeof window === "undefined") return;
+    const handlePopState = () => {
+      setLocation(getLocationInfo());
+    };
+    window.addEventListener("popstate", handlePopState);
+    return () => window.removeEventListener("popstate", handlePopState);
+  }, []);
+  const routerValue = react.useMemo(() => ({
+    pathname: location.pathname,
+    search: location.search,
+    href: location.href,
+    navigate,
+    params,
+    setParams
+  }), [location.pathname, location.search, location.href, navigate, params]);
+  return /* @__PURE__ */ jsxRuntime.jsx(SsrContext.Provider, { value: ssrData, children: /* @__PURE__ */ jsxRuntime.jsx(RouterContext.Provider, { value: routerValue, children }) });
+};
+RiktaProvider.displayName = "RiktaProvider";
+function useNavigation() {
+  const context = react.useContext(RouterContext);
+  const navigate = react.useCallback(
+    (url, options) => {
+      context.navigate(url, options);
+    },
+    [context.navigate]
+  );
+  return {
+    /** Navigate to a new URL */
+    navigate,
+    /** Current pathname */
+    pathname: context.pathname,
+    /** Current search string (without ?) */
+    search: context.search,
+    /** Full href */
+    href: context.href
+  };
+}
+var Link = ({
+  href,
+  replace = false,
+  scroll = true,
+  prefetch = false,
+  state,
+  children,
+  onClick,
+  ...restProps
+}) => {
+  const { navigate } = useNavigation();
+  const handleClick = react.useCallback(
+    (e) => {
+      onClick?.(e);
+      if (e.defaultPrevented) return;
+      if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+      if (e.button !== 0) return;
+      const target = e.currentTarget.target;
+      if (target && target !== "_self") return;
+      try {
+        const url = new URL(href, window.location.origin);
+        if (url.origin !== window.location.origin) return;
+      } catch {
+        return;
+      }
+      e.preventDefault();
+      navigate(href, { replace, scroll, state });
+    },
+    [href, replace, scroll, state, navigate, onClick]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx("a", { href, onClick: handleClick, ...restProps, children });
+};
+Link.displayName = "Link";
+function useParams() {
+  const context = react.useContext(RouterContext);
+  return context.params;
+}
+function useSearchParams() {
+  const context = react.useContext(RouterContext);
+  const searchParams = react.useMemo(() => {
+    return new URLSearchParams(context.search);
+  }, [context.search]);
+  const setSearchParams = react.useMemo(() => {
+    return (params) => {
+      const newParams = params instanceof URLSearchParams ? params : new URLSearchParams(params);
+      const search = newParams.toString();
+      const newUrl = search ? `${context.pathname}?${search}` : context.pathname;
+      context.navigate(newUrl, { scroll: false });
+    };
+  }, [context.pathname, context.navigate]);
+  return [searchParams, setSearchParams];
+}
+function useLocation() {
+  const context = react.useContext(RouterContext);
+  return {
+    pathname: context.pathname,
+    search: context.search,
+    href: context.href,
+    searchParams: new URLSearchParams(context.search)
+  };
+}
+function useSsrData() {
+  const context = react.useContext(SsrContext);
+  return context;
+}
+function useHydration() {
+  const isServer = typeof window === "undefined";
+  const [isHydrated, setIsHydrated] = react.useState(false);
+  react.useEffect(() => {
+    setIsHydrated(true);
+  }, []);
+  return {
+    isHydrated,
+    isServer
+  };
+}
+function useFetch(url, options = {}) {
+  const { skip = false, deps = [], transform, ...fetchOptions } = options;
+  const [state, setState] = react.useState({
+    data: null,
+    loading: !skip,
+    error: null
+  });
+  const mountedRef = react.useRef(true);
+  const fetchIdRef = react.useRef(0);
+  const fetchData = react.useCallback(async () => {
+    if (skip) return;
+    const fetchId = ++fetchIdRef.current;
+    setState((prev) => ({ ...prev, loading: true, error: null }));
+    try {
+      const response = await fetch(url, fetchOptions);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      let data = await response.json();
+      if (transform) {
+        data = transform(data);
+      }
+      if (fetchId === fetchIdRef.current && mountedRef.current) {
+        setState({ data, loading: false, error: null });
+      }
+    } catch (err) {
+      if (fetchId === fetchIdRef.current && mountedRef.current) {
+        const message = err instanceof Error ? err.message : "An error occurred";
+        setState({ data: null, loading: false, error: message });
+      }
+    }
+  }, [url, skip, JSON.stringify(fetchOptions), transform]);
+  react.useEffect(() => {
+    mountedRef.current = true;
+    fetchData();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [fetchData, ...deps]);
+  const refetch = react.useCallback(async () => {
+    await fetchData();
+  }, [fetchData]);
+  return {
+    ...state,
+    refetch
+  };
+}
+function useAction(url, options = {}) {
+  const {
+    onSuccess,
+    onError,
+    method = "POST",
+    headers: customHeaders = {}
+  } = options;
+  const [pending, setPending] = react.useState(false);
+  const [result, setResult] = react.useState(null);
+  const execute = react.useCallback(
+    async (input) => {
+      setPending(true);
+      setResult(null);
+      try {
+        const response = await fetch(url, {
+          method,
+          headers: {
+            "Content-Type": "application/json",
+            ...customHeaders
+          },
+          body: JSON.stringify(input)
+        });
+        const data = await response.json();
+        if (!response.ok) {
+          const actionResult2 = {
+            success: false,
+            error: data.message || data.error || `HTTP ${response.status}`,
+            fieldErrors: data.fieldErrors
+          };
+          setResult(actionResult2);
+          onError?.(actionResult2.error);
+          return actionResult2;
+        }
+        const actionResult = {
+          success: true,
+          data
+        };
+        setResult(actionResult);
+        onSuccess?.(data);
+        return actionResult;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "An error occurred";
+        const actionResult = {
+          success: false,
+          error: message
+        };
+        setResult(actionResult);
+        onError?.(message);
+        return actionResult;
+      } finally {
+        setPending(false);
+      }
+    },
+    [url, method, JSON.stringify(customHeaders), onSuccess, onError]
+  );
+  const reset = react.useCallback(() => {
+    setResult(null);
+  }, []);
+  return {
+    execute,
+    pending,
+    result,
+    reset
+  };
+}
+
+exports.Link = Link;
+exports.RiktaProvider = RiktaProvider;
+exports.RouterContext = RouterContext;
+exports.SsrContext = SsrContext;
+exports.useAction = useAction;
+exports.useFetch = useFetch;
+exports.useHydration = useHydration;
+exports.useLocation = useLocation;
+exports.useNavigation = useNavigation;
+exports.useParams = useParams;
+exports.useSearchParams = useSearchParams;
+exports.useSsrData = useSsrData;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map