npm package: @sacred-time/web
Description: Web plugin for displaying Islamic calendar dates with automatic location detection
Latest version: 1.0.0

# @sacred-time/web

Web plugin for easily integrating Islamic calendar dates into websites. Automatically detects user location and displays accurate dates based on sunset times.

## Features

- 🌍 **Automatic Location Detection**: Uses browser geolocation API with IP fallback
- ⏰ **Real-time Updates**: Automatically updates when date changes at sunset
- 📱 **Responsive Design**: Works on all screen sizes
- 🎨 **Customizable Styling**: Easy to customize with CSS
- ⚛️ **React Support**: React component included
- 🔌 **Easy Integration**: Works with vanilla JS, React, or any framework

## Installation

### NPM

```bash
npm install @sacred-time/web
```

### CDN (Coming Soon)

```html
<script src="https://cdn.jsdelivr.net/npm/@sacred-time/web/dist/index.umd.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@sacred-time/web/dist/styles.css">
```

## Usage

### Vanilla JavaScript

#### Basic Usage

```html
<div id="sacred-time-widget"></div>

<script src="path/to/sacred-time.umd.js"></script>
<script>
  SacredTime.initSacredTime({
    target: 'sacred-time-widget',
    autoDetectLocation: true
  });
</script>
```

#### With Custom Location

```javascript
SacredTime.initSacredTime({
  target: 'sacred-time-widget',
  location: {
    latitude: 24.7136,
    longitude: 46.6753
  },
  autoDetectLocation: false
});
```

#### With Backend Integration

```javascript
SacredTime.initSacredTime({
  target: 'sacred-time-widget',
  backendUrl: 'https://api.example.com',
  autoDetectLocation: true,
  onDateChange: (date) => {
    console.log('Date changed:', date);
  }
});
```

### React

```tsx
import { SacredTimeWidget } from '@sacred-time/web';

function App() {
  return (
    <SacredTimeWidget
      autoDetectLocation={true}
      onDateChange={(date) => console.log('Date:', date)}
    />
  );
}
```

#### React with Custom Props

```tsx
import { SacredTimeWidget } from '@sacred-time/web';

function App() {
  return (
    <SacredTimeWidget
      location={{ latitude: 24.7136, longitude: 46.6753 }}
      backendUrl="https://api.example.com"
      updateInterval={30000} // Update every 30 seconds
      format={{
        showMonthName: true,
        showYear: true
      }}
      className="my-custom-class"
      onDateChange={(date) => {
        // Handle date change
      }}
      onLocationDetected={(location) => {
        console.log('Location:', location);
      }}
      onError={(error) => {
        console.error('Error:', error);
      }}
    />
  );
}
```

### Programmatic API

```javascript
import { SacredTimePlugin } from '@sacred-time/web';

const plugin = new SacredTimePlugin({
  target: 'my-widget',
  autoDetectLocation: true
});

await plugin.init();

// Get current date
const date = plugin.getCurrentDate();
console.log(date);

// Update location manually
await plugin.updateLocation({
  latitude: 24.7136,
  longitude: 46.6753
});

// Stop auto-updates
plugin.stop();
```

## Configuration Options

### WebPluginConfig

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `target` | `string \| HTMLElement` | `'sacred-time-widget'` | Target element ID or element |
| `location` | `Location` | Auto-detected | User's location |
| `backendUrl` | `string` | `undefined` | Backend API URL for moon sightings |
| `updateInterval` | `number` | `60000` | Update interval in milliseconds |
| `format` | `object` | See below | Display format options |
| `classPrefix` | `string` | `'sacred-time'` | CSS class prefix |
| `autoDetectLocation` | `boolean` | `true` | Auto-detect user location |
| `onDateChange` | `function` | `undefined` | Callback when date changes |
| `onLocationDetected` | `function` | `undefined` | Callback when location detected |
| `onError` | `function` | `undefined` | Callback on error |

### Format Options

```typescript
format: {
  showMonthName?: boolean;  // Default: true
  showYear?: boolean;      // Default: true
  customFormat?: (date: { year: number; month: number; day: number }) => string;
}
```

## Styling

The widget comes with default styles, but you can customize them:

```css
/* Override default styles */
.sacred-time__container {
  background: your-color;
  border-radius: your-radius;
}

.sacred-time__day {
  font-size: your-size;
  color: your-color;
}
```

### Theme Variants

Add these classes to your target element:

- `sacred-time--dark`: Dark theme
- `sacred-time--light`: Light theme
- `sacred-time--minimal`: Minimal styling

```html
<div id="sacred-time-widget" class="sacred-time--dark"></div>
```

## Location Detection

The plugin tries to detect location in this order:

1. **Browser Geolocation API**: Most accurate, requires user permission
2. **IP-based Detection**: Fallback using IP geolocation service
3. **Default Location**: Falls back to Makkah (21.3891, 39.8579) if all else fails

## Browser Support

- Chrome/Edge: ✅ Full support
- Firefox: ✅ Full support
- Safari: ✅ Full support
- IE11: ❌ Not supported (use polyfills if needed)

## Examples

See the `examples/` directory for:
- `vanilla.html` - Vanilla JavaScript example
- `react-example.tsx` - React component example

## License

MIT