npm package: @samryansoftware/realestate-react
Description: React library for SR Dreams Real Estate API
Author: SR Dreams
Latest version: 1.0.0

# @samryansoftware/realestate-react

A React library for integrating with the SR Dreams Real Estate API. This library provides context providers, hooks, and reusable components for building real estate websites.

## Installation

```bash
npm install @samryansoftware/realestate-react
```

## Quick Start

### 1. Wrap your app with the context provider

```jsx
import { SRDContextProvider } from '@samryansoftware/realestate-react';

function App() {
  return (
    <SRDContextProvider config={{ realtorId: '123abc' }}>
      <YourApp />
    </SRDContextProvider>
  );
}
```

### 2. Use the components and hooks

```jsx
import { 
  RealtorProfile, 
  PropertyList, 
  useRealtor, 
  useProperties 
} from '@samryansoftware/realestate-react';

function RealtorPage() {
  const { realtor, loading } = useRealtor();
  const { properties } = useProperties();

  return (
    <div>
      <RealtorProfile />
      <PropertyList showPagination={true} />
    </div>
  );
}
```

## API Reference

### SRDContextProvider

The main context provider that manages API state and data fetching.

```jsx
<SRDContextProvider config={config}>
  {children}
</SRDContextProvider>
```

#### Config Options

- `realtorId` (string): The realtor ID to fetch data for
- `baseUrl` (string, optional): Custom API base URL (defaults to `https://realestateapi.srdreams.com/api/public`)

### Hooks

#### useSRD()

Returns the full context with all state and actions.

```jsx
const { realtor, properties, loading, error, fetchRealtor, fetchProperties } = useSRD();
```

#### useRealtor()

Returns realtor-specific data and actions.

```jsx
const { realtor, loading, error, fetchRealtor, clearError } = useRealtor();
```

#### useProperties()

Returns properties-specific data and actions.

```jsx
const { properties, propertiesLoading, propertiesError, pagination, fetchProperties } = useProperties();
```

#### useProperty(propertyId)

Returns data for a specific property.

```jsx
const { property, loading, error, refetch } = useProperty('property123');
```

### Components

#### RealtorProfile

Displays realtor information with avatar and contact details.

```jsx
<RealtorProfile 
  showAvatar={true}
  showContact={true}
  showStats={false}
  className="custom-class"
/>
```

#### RealtorAvatar

Displays just the realtor's avatar.

```jsx
<RealtorAvatar 
  size="medium" // 'small' | 'medium' | 'large'
  className="custom-class"
/>
```

#### RealtorContact

Displays contact information with clickable email and phone links.

```jsx
<RealtorContact 
  showEmail={true}
  showPhone={true}
  className="custom-class"
/>
```

#### PropertyList

Displays a list of properties with filtering and pagination.

```jsx
<PropertyList 
  filters={{ status: 'active', minPrice: 200000 }}
  layout="grid" // 'grid' | 'list'
  showPagination={true}
  itemsPerPage={12}
  onPropertyClick={(property) => console.log(property)}
  renderProperty={(property) => <CustomPropertyCard property={property} />}
/>
```

#### PropertyCard

Displays a single property card.

```jsx
<PropertyCard 
  property={property}
  showImages={true}
  showDetails={true}
  showRealtor={false}
  className="custom-class"
/>
```

#### PropertyFilter

Provides filtering controls for properties.

```jsx
<PropertyFilter 
  onFiltersChange={(filters) => console.log(filters)}
  currentFilters={{ status: 'active' }}
  className="custom-class"
/>
```

#### PropertyPagination

Displays pagination controls.

```jsx
<PropertyPagination 
  pagination={pagination}
  currentPage={currentPage}
  onPageChange={setCurrentPage}
  className="custom-class"
/>
```

### Standalone API Functions

For use outside of React components:

```jsx
import { srdAPI } from '@srdreams/realestate-react';

// Get realtor
const realtor = await srdAPI.getRealtor('123abc');

// Get properties with filters
const properties = await srdAPI.getProperties('123abc', {
  status: 'active',
  minPrice: 200000,
  maxPrice: 500000,
  sort: 'price:asc'
});

// Get specific property
const property = await srdAPI.getProperty('property123');

// Get all realtors
const realtors = await srdAPI.getAllRealtors({
  search: 'john',
  sort: 'name:asc'
});
```

## Filter Options

### Property Filters

- `status`: 'active' | 'pending' | 'sold'
- `type`: 'house' | 'apartment' | 'condo' | 'townhouse' | 'land'
- `minPrice`: number
- `maxPrice`: number
- `search`: string (searches title, description, address)
- `sort`: string (format: 'field:direction')
- `page`: number
- `limit`: number

### Sort Options

- `price:asc` - Price low to high
- `price:desc` - Price high to low
- `createdAt:desc` - Newest first
- `createdAt:asc` - Oldest first
- `title:asc` - Title A-Z

## Examples

### Complete Realtor Website

```jsx
import { 
  SRDContextProvider, 
  RealtorProfile, 
  PropertyList, 
  PropertyFilter 
} from '@samryansoftware/realestate-react';

function RealtorWebsite() {
  const [filters, setFilters] = useState({});

  return (
    <SRDContextProvider config={{ realtorId: '123abc' }}>
      <div>
        <header>
          <RealtorProfile showStats={true} />
        </header>
        
        <main>
          <PropertyFilter onFiltersChange={setFilters} />
          <PropertyList 
            filters={filters}
            showPagination={true}
            onPropertyClick={(property) => {
              window.location.href = `/property/${property._id}`;
            }}
          />
        </main>
      </div>
    </SRDContextProvider>
  );
}
```

### Property Detail Page

```jsx
import { SRDContextProvider, useProperty } from '@samryansoftware/realestate-react';

function PropertyDetail({ propertyId }) {
  return (
    <SRDContextProvider config={{ realtorId: '123abc' }}>
      <PropertyDetailContent propertyId={propertyId} />
    </SRDContextProvider>
  );
}

function PropertyDetailContent({ propertyId }) {
  const { property, loading, error } = useProperty(propertyId);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!property) return <div>Property not found</div>;

  return (
    <div>
      <h1>{property.title}</h1>
      <p>${property.price.toLocaleString()}</p>
      <p>{property.address}</p>
      <p>{property.description}</p>
      
      <div>
        {property.images.map((image, index) => (
          <img key={index} src={image.url} alt={image.alt} />
        ))}
      </div>
    </div>
  );
}
```

## Styling

The library uses CSS classes with the `srd-` prefix. You can override styles by targeting these classes:

```css
.srd-realtor-profile {
  /* Custom styles */
}

.srd-property-card {
  /* Custom styles */
}

.srd-pagination {
  /* Custom styles */
}
```

## Error Handling

All components and hooks include error handling:

```jsx
const { error, clearError } = useRealtor();

if (error) {
  return (
    <div>
      <p>Error: {error}</p>
      <button onClick={clearError}>Try Again</button>
    </div>
  );
}
```

## TypeScript Support

The library is fully typed with TypeScript. All interfaces are exported:

```jsx
import { Realtor, Property, PropertyFilters } from '@samryansoftware/realestate-react';

interface MyComponentProps {
  realtor: Realtor;
  filters: PropertyFilters;
}
```

## License

MIT