@archbase/ssr 3.0.0

package/README.md

@@ -0,0 +1,411 @@
+# @archbase/ssr
+
+Server-Side Rendering utilities for Archbase React components with TanStack Start support.
+
+## Installation
+
+```bash
+npm install @archbase/ssr
+# or
+yarn add @archbase/ssr
+# or
+pnpm add @archbase/ssr
+```
+
+## Peer Dependencies
+
+```bash
+npm install react react-dom @mantine/core @mantine/hooks @tanstack/react-query @tanstack/start
+```
+
+## Features
+
+### 🚀 **TanStack Start Integration**
+- Full SSR support for TanStack Start applications
+- Seamless server/client data synchronization
+- Optimized hydration strategies
+
+### 📊 **DataSource SSR Support**
+- SSR-compatible DataSource implementations
+- State serialization/deserialization
+- Automatic hydration from server data
+
+### 🎯 **SSR-Safe Components**
+- Hydration-safe providers and hooks
+- Client-only and server-only components
+- Media query hooks that work with SSR
+
+### ⚡ **Performance Optimized**
+- Minimal payload serialization
+- Streaming-compatible
+- Lazy hydration support
+
+## Basic Setup
+
+### 1. Wrap your app with ArchbaseSSRProvider
+
+```typescript
+// app.tsx (TanStack Start)
+import { ArchbaseSSRProvider, ArchbaseTanStackProvider } from '@archbase/ssr';
+import { QueryClient } from '@tanstack/react-query';
+
+function App() {
+  const queryClient = new QueryClient();
+
+  return (
+    <ArchbaseSSRProvider>
+      <ArchbaseTanStackProvider queryClient={queryClient}>
+        <YourAppContent />
+      </ArchbaseTanStackProvider>
+    </ArchbaseSSRProvider>
+  );
+}
+```
+
+### 2. Use SSR-compatible DataSources
+
+```typescript
+import { useArchbaseSSRDataSource } from '@archbase/ssr';
+
+function UsersList() {
+  const {
+    dataSource,
+    isLoading,
+    error,
+    isHydrated
+  } = useArchbaseSSRDataSource('users', {
+    initialRecords: [], // Server-side initial data
+    autoHydrate: true,
+    fallbackRecords: []
+  });
+
+  if (!isHydrated) {
+    return <div>Loading...</div>; // SSR placeholder
+  }
+
+  return (
+    <div>
+      {dataSource.getRecords().map(user => (
+        <div key={user.id}>{user.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Advanced Usage
+
+### Server-Side Data Fetching with TanStack Start
+
+```typescript
+// routes/users.tsx
+import { createFileRoute } from '@tanstack/react-router';
+import { useArchbaseQuery, prepareServerQueries } from '@archbase/ssr';
+
+export const Route = createFileRoute('/users')({
+  component: UsersPage,
+  loader: async ({ context }) => {
+    // Prepare queries for SSR
+    const queryClient = context.queryClient;
+    
+    await prepareServerQueries(queryClient, [
+      {
+        key: ['users'],
+        fetchFn: () => fetch('/api/users').then(res => res.json())
+      }
+    ]);
+
+    return {
+      dehydratedState: queryClient.getQueryData(['users'])
+    };
+  }
+});
+
+function UsersPage() {
+  const { dataSource } = useArchbaseSSRDataSource('users');
+  
+  const { data, isLoading } = useArchbaseQuery(
+    ['users'],
+    () => fetch('/api/users').then(res => res.json()),
+    {
+      dataSource,
+      syncWithDataSource: true,
+      ssr: true
+    }
+  );
+
+  return (
+    <div>
+      <h1>Users</h1>
+      {/* Your user list component */}
+    </div>
+  );
+}
+```
+
+### SSR-Safe Utilities
+
+```typescript
+import { 
+  canUseDOM, 
+  safeLocalStorage, 
+  withSSRFallback,
+  ClientOnly,
+  ServerOnly
+} from '@archbase/ssr';
+
+function MyComponent() {
+  // Safe localStorage access
+  const savedData = safeLocalStorage.getItem('userData');
+  
+  // Safe operation with fallback
+  const windowWidth = withSSRFallback(
+    () => window.innerWidth,
+    1024 // fallback for SSR
+  );
+
+  return (
+    <div>
+      <ServerOnly>
+        <div>This only renders on server</div>
+      </ServerOnly>
+      
+      <ClientOnly fallback={<div>Loading...</div>}>
+        <div>This only renders on client after hydration</div>
+      </ClientOnly>
+    </div>
+  );
+}
+```
+
+### Hydration-Safe State Management
+
+```typescript
+import { useHydrationSafeState, useSSRSafeMediaQuery } from '@archbase/ssr';
+
+function ResponsiveComponent() {
+  // Media query that works with SSR
+  const isMobile = useSSRSafeMediaQuery('(max-width: 768px)', false);
+  
+  // State that's safe during hydration
+  const theme = useHydrationSafeState(
+    'light', // SSR value
+    () => localStorage.getItem('theme') || 'light' // Client value
+  );
+
+  return (
+    <div className={`theme-${theme} ${isMobile ? 'mobile' : 'desktop'}`}>
+      Content
+    </div>
+  );
+}
+```
+
+### Advanced DataSource Serialization
+
+```typescript
+import { ArchbaseSSRDataSource } from '@archbase/ssr';
+
+// Create SSR-compatible DataSource
+const userDataSource = new ArchbaseSSRDataSource('users');
+
+// On server - serialize state
+const serializedState = userDataSource.serializeState();
+
+// Send to client and deserialize
+userDataSource.deserializeState(serializedState);
+
+// Or use minimal serialization for performance
+const minimalState = userDataSource.serializeMinimalState();
+
+// Create from server data
+const hydratedDataSource = ArchbaseSSRDataSource.fromServerData(
+  'users',
+  serverData,
+  { /* options */ }
+);
+```
+
+### Multiple DataSources Management
+
+```typescript
+import { useArchbaseSSRDataSources } from '@archbase/ssr';
+
+function Dashboard() {
+  const {
+    sources,
+    getDataSource,
+    serializeAll,
+    isAnyLoading,
+    errors
+  } = useArchbaseSSRDataSources([
+    { name: 'users', options: { initialRecords: [] } },
+    { name: 'products', options: { initialRecords: [] } },
+    { name: 'orders', options: { initialRecords: [] } }
+  ]);
+
+  const userDataSource = getDataSource('users');
+  const productDataSource = getDataSource('products');
+
+  if (isAnyLoading) {
+    return <div>Loading dashboard...</div>;
+  }
+
+  return (
+    <div>
+      <UsersList dataSource={userDataSource?.dataSource} />
+      <ProductsList dataSource={productDataSource?.dataSource} />
+    </div>
+  );
+}
+```
+
+## TanStack Start Route Example
+
+Complete example of a TanStack Start route with Archbase SSR:
+
+```typescript
+// routes/products/$productId.tsx
+import { createFileRoute } from '@tanstack/react-router';
+import { 
+  ArchbaseSSRProvider,
+  useArchbaseSSRDataSource,
+  prepareServerQueries 
+} from '@archbase/ssr';
+
+export const Route = createFileRoute('/products/$productId')({
+  component: ProductPage,
+  loader: async ({ params, context }) => {
+    const { productId } = params;
+    const queryClient = context.queryClient;
+
+    // Prefetch product data on server
+    await prepareServerQueries(queryClient, [
+      {
+        key: ['product', productId],
+        fetchFn: () => fetchProduct(productId)
+      }
+    ]);
+
+    const productData = queryClient.getQueryData(['product', productId]);
+
+    return {
+      productData,
+      dehydratedState: queryClient.getQueryData(['product', productId])
+    };
+  }
+});
+
+function ProductPage() {
+  const { productId } = Route.useParams();
+  const { productData } = Route.useLoaderData();
+
+  const { dataSource, isHydrated } = useArchbaseSSRDataSource('product', {
+    initialRecords: productData ? [productData] : [],
+    autoHydrate: true
+  });
+
+  if (!isHydrated) {
+    // SSR/hydration loading state
+    return <ProductSkeleton />;
+  }
+
+  const product = dataSource.getCurrentRecord();
+
+  return (
+    <div>
+      <h1>{product?.name}</h1>
+      <p>{product?.description}</p>
+      <ProductForm dataSource={dataSource} />
+    </div>
+  );
+}
+
+async function fetchProduct(id: string) {
+  const response = await fetch(`/api/products/${id}`);
+  return response.json();
+}
+```
+
+## Best Practices
+
+### 1. **Minimize Serialized Data**
+```typescript
+// Good: Only serialize essential data
+const minimalState = dataSource.serializeMinimalState();
+
+// Avoid: Serializing large datasets
+const fullState = dataSource.serializeState(); // Use sparingly
+```
+
+### 2. **Graceful Fallbacks**
+```typescript
+const { dataSource, error } = useArchbaseSSRDataSource('users', {
+  fallbackRecords: [], // Always provide fallbacks
+  autoHydrate: true
+});
+
+if (error) {
+  return <ErrorBoundary error={error} />;
+}
+```
+
+### 3. **Conditional Client Features**
+```typescript
+import { ClientOnly, canUseDOM } from '@archbase/ssr';
+
+function AdvancedFeatures() {
+  return (
+    <ClientOnly fallback={<BasicView />}>
+      {canUseDOM() && <InteractiveChart />}
+    </ClientOnly>
+  );
+}
+```
+
+### 4. **Performance Optimization**
+```typescript
+// Lazy load heavy components
+const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
+
+function App() {
+  return (
+    <ClientOnly>
+      <React.Suspense fallback={<Loading />}>
+        <HeavyComponent />
+      </React.Suspense>
+    </ClientOnly>
+  );
+}
+```
+
+## Migration from Client-Only Archbase
+
+1. **Wrap your app with SSR providers**
+2. **Replace DataSource with useArchbaseSSRDataSource**
+3. **Add SSR-safe utilities where needed**
+4. **Update server routes for data prefetching**
+
+## TypeScript Support
+
+All components and hooks are fully typed with TypeScript. The package includes complete type definitions for optimal development experience.
+
+## Browser Compatibility
+
+- **Server**: Node.js 18+
+- **Client**: Modern browsers with ES2020 support
+- **SSR**: Full support for all server-side environments
+
+## Performance
+
+- **Bundle Size**: ~15KB gzipped
+- **Runtime Overhead**: Minimal (hydration detection only)
+- **Memory Usage**: Optimized serialization reduces memory footprint
+
+## Contributing
+
+This package is part of the Archbase React ecosystem. See the main repository for contribution guidelines.
+
+## License
+
+MIT License

package/dist/datasource/ArchbaseSSRDataSource.d.ts

@@ -0,0 +1,122 @@
+import { ArchbaseDataSource } from '@archbase/data';
+/**
+ * Interface for serializable DataSource state
+ */
+interface SerializableDataSourceState<T, ID> {
+    records: T[];
+    currentRecord: T | undefined;
+    recordIndex: number;
+    state: string;
+    hasChanges: boolean;
+    filter?: any;
+    sort?: any;
+    metadata?: Record<string, any>;
+}
+/**
+ * Extended DataSource with SSR capabilities
+ */
+export declare class ArchbaseSSRDataSource<T extends Record<string, any>, ID> extends ArchbaseDataSource<T, ID> {
+    private _ssrData?;
+    private _isHydrating;
+    constructor(name: string, options?: any);
+    /**
+     * Serialize DataSource state for SSR
+     */
+    serializeState(): string;
+    /**
+     * Restore DataSource state from serialized data
+     */
+    deserializeState(serializedState: string): void;
+    /**
+     * Check if DataSource is currently hydrating from SSR
+     */
+    isHydrating(): boolean;
+    /**
+     * Get SSR data if available
+     */
+    getSSRData(): SerializableDataSourceState<T, ID> | undefined;
+    /**
+     * Create a minimal state object for SSR
+     * Only includes essential data to reduce payload size
+     */
+    serializeMinimalState(): string;
+    /**
+     * Create a DataSource instance from server data
+     */
+    static fromServerData<T extends Record<string, any>, ID>(name: string, serverData: any, options?: any): ArchbaseSSRDataSource<T, ID>;
+    /**
+     * Enhanced method to handle SSR-safe operations
+     */
+    ssrSafeOperation<R>(operation: () => R, fallback: R): R;
+    /**
+     * Override to handle SSR-safe filtering
+     */
+    applyFilter(filter: any): void;
+    /**
+     * Override to handle SSR-safe sorting
+     */
+    applySort(sort: any): void;
+    /**
+     * Get records with SSR safety
+     */
+    getRecords(): T[];
+    /**
+     * Get current record with SSR safety
+     */
+    getCurrentRecord(): T | undefined;
+    /**
+     * Check if we have data available for rendering
+     */
+    hasData(): boolean;
+    /**
+     * Create a snapshot that can be safely transmitted between server/client
+     */
+    createSnapshot(): {
+        records: T[];
+        currentIndex: number;
+        metadata: Record<string, any>;
+        timestamp: number;
+    };
+    /**
+     * Restore from a snapshot
+     */
+    restoreFromSnapshot(snapshot: {
+        records: T[];
+        currentIndex: number;
+        metadata: Record<string, any>;
+        timestamp: number;
+    }): void;
+    /**
+     * Helper method to get all metadata
+     */
+    private getAllMetadata;
+    /**
+     * Get all records from the data source
+     */
+    getAllRecords(): T[];
+    /**
+     * Get current record index
+     */
+    getRecordIndex(): number;
+    /**
+     * Check if data source has changes
+     */
+    isChanged(): boolean;
+    /**
+     * Get current filter
+     */
+    getFilter(): any;
+    /**
+     * Get current sort
+     */
+    getSort(): any;
+    /**
+     * Get record count
+     */
+    getRecordCount(): number;
+    /**
+     * Set records with proper DataSource options
+     */
+    private setRecords;
+}
+export {};

package/dist/hooks/useArchbaseSSRDataSource.d.ts

@@ -0,0 +1,94 @@
+import { ArchbaseSSRDataSource } from '../datasource/ArchbaseSSRDataSource';
+interface UseArchbaseSSRDataSourceOptions<T, ID> {
+    /** Initial records for SSR */
+    initialRecords?: T[];
+    /** Server data key in SSR context */
+    serverDataKey?: string;
+    /** Auto-hydrate from server data */
+    autoHydrate?: boolean;
+    /** Fallback records if server data fails */
+    fallbackRecords?: T[];
+    /** Custom serialization/deserialization */
+    serializer?: {
+        serialize: (data: any) => string;
+        deserialize: (data: string) => any;
+    };
+}
+/**
+ * SSR-compatible hook for DataSource management
+ */
+export declare function useArchbaseSSRDataSource<T extends Record<string, any>, ID>(name: string, options?: UseArchbaseSSRDataSourceOptions<T, ID>): {
+    dataSource: ArchbaseSSRDataSource<T, ID>;
+    isLoading: boolean;
+    error: Error | null;
+    isHydrated: boolean;
+    serializeState: () => string;
+    deserializeState: (serializedState: string) => void;
+    getMinimalState: () => {
+        recordCount: number;
+        currentIndex: number;
+        hasData: boolean;
+        isActive: boolean;
+    };
+    refresh: (newRecords?: T[]) => Promise<void>;
+    records: T[];
+    currentRecord: T | undefined;
+    recordCount: number;
+    hasData: boolean;
+};
+/**
+ * Hook for managing multiple DataSources with SSR
+ */
+export declare function useArchbaseSSRDataSources<T extends Record<string, any>, ID>(dataSources: Array<{
+    name: string;
+    options?: UseArchbaseSSRDataSourceOptions<T, ID>;
+}>): {
+    sources: {
+        dataSource: ArchbaseSSRDataSource<T, ID>;
+        isLoading: boolean;
+        error: Error | null;
+        isHydrated: boolean;
+        serializeState: () => string;
+        deserializeState: (serializedState: string) => void;
+        getMinimalState: () => {
+            recordCount: number;
+            currentIndex: number;
+            hasData: boolean;
+            isActive: boolean;
+        };
+        refresh: (newRecords?: T[] | undefined) => Promise<void>;
+        records: T[];
+        currentRecord: T | undefined;
+        recordCount: number;
+        hasData: boolean;
+        name: string;
+    }[];
+    getDataSource: (name: string) => {
+        dataSource: ArchbaseSSRDataSource<T, ID>;
+        isLoading: boolean;
+        error: Error | null;
+        isHydrated: boolean;
+        serializeState: () => string;
+        deserializeState: (serializedState: string) => void;
+        getMinimalState: () => {
+            recordCount: number;
+            currentIndex: number;
+            hasData: boolean;
+            isActive: boolean;
+        };
+        refresh: (newRecords?: T[] | undefined) => Promise<void>;
+        records: T[];
+        currentRecord: T | undefined;
+        recordCount: number;
+        hasData: boolean;
+        name: string;
+    } | undefined;
+    serializeAll: () => Record<string, string>;
+    isAnyLoading: boolean;
+    errors: {
+        name: string;
+        error: Error | null;
+    }[];
+    isHydrated: boolean;
+};
+export {};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { isServer, isClient, canUseDOM, safeLocalStorage, safeSessionStorage, serializeForSSR, deserializeFromSSR, createSSRId, resetSSRIdCounter, getWindow, getDocument, hasFeature, withSSRFallback, clientOnly, serverOnly, createHydrationSafeValue, getMediaQuery, type MediaQueryResult } from './utils/ArchbaseSSRUtils';
+export { ArchbaseSSRProvider, useArchbaseSSR, useHydrationSafeState, ClientOnly, ServerOnly, useClientEffect, useSSRSafeMediaQuery } from './providers/ArchbaseSSRProvider';
+export { ArchbaseSSRDataSource } from './datasource/ArchbaseSSRDataSource';
+export { useArchbaseSSRDataSource, useArchbaseSSRDataSources } from './hooks/useArchbaseSSRDataSource';
+export { ArchbaseTanStackProvider, useArchbaseQuery, serializeQueryClientState, prepareServerQueries, withArchbaseTanStack } from './tanstack/ArchbaseTanStackIntegration';
+export declare const ArchbaseSSRVersion = "3.0.0";